Add support for elements validation in DataForm's array fields #71194

elazzabi · 2025-08-13T14:34:24Z

What?

This adds support for validation in DataForm's array fields. The following prop can be used to only accept input from the elements:

isValid: {
	elements: true,
}

Why?

This allows the component to be customized depending on use cases.

How?

Testing Instructions

Add this to any Storybook implementation to test this.

isValid: {
	elements: true,
}

Testing Instructions for Keyboard

Screenshots or screencast

This is the only mode currently supported:

CleanShot.2025-08-13.at.15.31.54.mp4

This is the new mode:

CleanShot.2025-08-13.at.15.31.06.mp4

github-actions · 2025-08-13T14:34:39Z

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: elazzabi <elazzabi@git.wordpress.org>
Co-authored-by: oandregal <oandregal@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>

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

…lements using `findElementByLabel` instead of `isItemValid`.

…s are valid elements and streamline single-value checks for element validity.

… specified elements.

oandregal

Nice progress here. I think the missing bit is how/whether the FormTokenField can display messages to users (validation errors) and/or signal invalid state via color, like other controls do. cc @mirka @jameskoster for thoughts

oandregal · 2025-08-18T12:15:58Z

packages/dataviews/src/validation.ts

+					return false;
+				}
+				// For single-value fields, check if the value is a valid element
+				return validValues.includes( value );


In addition to this, we need to display what's happening to the user.

Take the text control as an example. We handle isValid.required and isValid.custom there. By introducing isValid.elements we need to communicate that as well (we could use the customValidator function of the control to display something along the lines of "Value must be one of the elements".

I added an error when this happens

…ules and predefined options

mirka · 2025-08-19T16:14:04Z

how/whether the FormTokenField can display messages to users (validation errors) and/or signal invalid state via color, like other controls do.

Yes, I think there can be a ValidatedFormTokenControl.

…tion with custom and required checks

… isValid elements is passed

…lue handling.

…les and predefined options

elazzabi · 2025-08-22T10:18:20Z

@mirka @oandregal I added a ValidatedFormTokenControl to wrap the component with some messaging. I also added 2 validation examples to the Storybook. Here's the current behavior:

CleanShot.2025-08-22.at.11.09.55.mp4

oandregal · 2025-08-22T12:29:01Z

packages/dataviews/src/validation.ts

 				( field.type === 'integer' &&
 					isEmptyNullOrUndefined( value ) ) ||
+				( field.type === 'array' &&
+					isNotArrayEmptyOrContainsInvalidElements( value ) ) ||


This is a small nit. For a second, I was confused for the use of "invalid elements" here, I thought why are we validating isValid.elements here if there's a specific check for it? Perhaps something along these lines makes that more clear?

Suggested change

isNotArrayEmptyOrContainsInvalidElements( value ) ) ||

isArrayOrElementsEmptyNullOrUndefined( value ) ) ||

oandregal · 2025-08-22T12:36:49Z

packages/dataviews/src/field-types/array.tsx

 			}

-			if ( field?.elements ) {
+			if ( field?.elements && field.isValid?.elements ) {


Given isValid.elements is implemented in validation.ts, do we still need it here? (same for any other field type)

I added this because, without it, the validation is run whenever the elements are present. Including when it is okay to add new elements

CleanShot.2025-08-22.at.15.23.13.mp4

Is this code ever executed? I'd think we can remove it because it's covered by the control here, and so it never checks the custom validation here (that will run the same check again for elements).

There are a few levels to validation:

Control-level: the array control handles element validation, providing the corresponding message if it's invalid.

Form-level, via the isItemValid utility: this handles element validation (this is for form-level).

By introducing isValid.elements I understand that we can:

remove the existing checks in all field types (previously bundled as part of isValid.custom)

make sure every control handles isValid.elements properly (done for the array control)

make sure isItemValid also handles it (done)

Does this make sense, or am I missing any context here?

After seeing it closely, I agree that this part was inadvertently executed (as I recorded in the video), but it should be removed altogether f2e301d

Now that it is removed, and regarding this part:

make sure every control handles isValid.elements properly (done for the array control)

I only see the select control that might benefit from such validation. Should I implement it there, too?

oandregal

I ran into this (adding two elements, the first in Titlecase the second in lowercase):

Screen.Recording.2025-08-22.at.14.43.37.mov

It doesn't happen in the FormToken component:

Screen.Recording.2025-08-22.at.14.45.58.mov

oandregal · 2025-08-22T12:48:36Z

Hey @elazzabi this is really close, thanks for keep pushing. I think we need to solve a couple of glitches and it's ready to merge.

mirka · 2025-08-22T13:27:11Z

packages/dataviews/src/dataform-controls/array.tsx

+// Create a validated FormTokenField wrapper
+const ValidatedFormTokenControl = ( {


Sorry for being unclear, I meant we can add a ValidatedFormTokenControl component to @wordpress/components, along with the other ones 😄

Please open a separate PR for this addition so we can do a component review. And do let me know if you find anything lacking in the existing documentation 🙏

Oh okay. @oandregal I'll implement this change ^ first before continuing, hopefully it will reduce the diff here 😄

@mirka I created a PR for the component here #71350

Let me know if you have any feedback

elazzabi · 2025-09-11T08:58:46Z

I still see the issue with adding elements in different case (title vs lowercase):

@oandregal that is because the elements we pass to the field have a label of "Astronomy" and a value of "astronomy". So even if it's displayed as "Astronomy", the underlying value is lowercase, which is considered the same.

Here's how it works with "asia" and "Asia" (neither is part of the elements), for example. Both are accepted:

CleanShot.2025-09-11.at.09.56.18.mp4

astronomy, and Astronomy will also be both accepted, but both will be displayed as "Astronomy" given the initial elements we pass

oandregal · 2025-09-11T09:08:44Z

I'm unable to clean the error message when the input loses focus

This sounds like we're clearing the input too early, before the values are committed? As a result, there's a discrepancy between the committed values in the component and what the validation sees. I'm only speculating based on testing the component, haven't looked at the code yet.

Note the difference (the countries component's input is cleared when I click outside, but the categories one doesn't):

Screen.Recording.2025-09-11.at.11.05.09.mov

The ValidatedFormToken doesn't do any clearing either:

Screen.Recording.2025-09-11.at.11.05.34.mov

packages/components/CHANGELOG.md

Co-authored-by: André <583546+oandregal@users.noreply.github.com>

elazzabi · 2025-09-11T09:24:19Z

@oandregal oh yes, great catch! Looks like this is something in the FormTokenField component

EDIT: I feel like the FormTokenField component should call onInputChange after this reset, given the content has changed. This way, we can integrate the error clearing into the change event

EDIT 2: I pushed the changes to fix this in 6ef2a57 & fe03b3d. Working great now! Thanks for the pointers @oandregal !

…/gutenberg into add/elements-validation

…idation

oandregal · 2025-09-11T11:33:12Z

@elazzabi could you also update the docs for validation to include isValid.elements?

oandregal · 2025-09-17T09:11:33Z

packages/components/src/form-token-field/index.tsx

 		} else {
 			// Reset to initial state
 			setIncompleteTokenValue( '' );
+			onInputChange( '' );


Could you clarify what is this for?

I'm not super familiar with the FormToken component, but this is not clearing internal state. It's triggering the onInputChange user callback when the component loses focus under certain conditions. It seems weird.

Tried testing the components themselves (both validated and the normal version) but I don't know how to trigger this path. It'd be great if you could share more about this.

Sure!

The FormToken component accepts a onInputChange prop that I think should be called when the input is changed. Here, when the user clicks outside the input, we setIncompleteTokenValue( '' ) but we were not letting the parent component know about the change.

In practice, this is how it looks without onInputChange:

CleanShot.2025-09-18.at.10.42.45.mp4

This is how it looks with it:

CleanShot.2025-09-18.at.10.39.45.mp4

(The error message is cleaned after navigating away)

In summary, we need to inform the parent about the input change to remove the error message.

I continued the conversation here #71194 (comment)

packages/dataviews/src/dataform-controls/array.tsx

oandregal · 2025-09-17T12:50:05Z

packages/dataviews/src/dataform-controls/array.tsx

-			value={ arrayValue }
+			value={ arrayValueAsElements }
 			onChange={ onChangeControl }
+			onInputChange={ onInputChange }


So, onValidate triggers for every onChange event. And the user is never able to introduce invalid data as per __experimentalValidateInput. So, the only case in which we ever display an error for isValid.elements is when the case in which the component loads with bad data (as here). Is this correct?

If so, why we need this? The custom error for elements will never happen as a result of an input event, so it doesn't need to be cleared when input is empty. Perhaps I'm not considering another use case?

The only reason for this is to catch this edge case, where the input is cleared but the message stays:

CleanShot.2025-09-18.at.10.42.45.mp4

@elazzabi I've pushed 20410e4 to illustrate my point. It essentially removes everything related to input. We use __experimentalValidateInput to prevent an invalid element from being committed, but we don't trigger any validation on input.

I need to look at other things now, but there's this question we need to answer: does it makes sense to just remove onValidate / customValidity logic altogether? I think the only case where this may be useful is when the component is loaded with data that is not part of the element list.

I think the only case where this may be useful is when the component is loaded with data that is not part of the element list.

So I tested this scenario now by adding es to the data that gets loaded. This is the result:

Screen.Recording.2025-09-19.at.17.57.12.mov

I think we can keep that logic, but the message needs to be more specific. Along the lines of: Please select from the available options: "es" is invalid..

Thanks for the commit @oandregal !

In this case, we are completely removing the feedback when the user tries to insert an element via "," (ie nothing happens), but I'm okay keeping it that way.

I pushed a change to update the message with two versions (singular and plural):

elazzabi added 2 commits August 13, 2025 15:13

Add support for validating elements

000595e

Add validation input and how to

cf015c5

elazzabi requested a review from oandregal as a code owner August 13, 2025 14:34

oandregal assigned elazzabi Aug 13, 2025

oandregal added [Type] Enhancement A suggestion for improvement. [Feature] DataViews Work surrounding upgrading and evolving views in the site editor and beyond labels Aug 13, 2025

elazzabi added 4 commits August 15, 2025 12:06

Add array validation with required param

14e0308

Update validation logic to check if the token matches any available e…

59ade44

…lements using `findElementByLabel` instead of `isItemValid`.

Enhance validation logic to support array types by ensuring all value…

1db0a20

…s are valid elements and streamline single-value checks for element validity.

Add tests for array and text field validations and validating against…

b7b321a

… specified elements.

oandregal reviewed Aug 18, 2025

View reviewed changes

Add categories field to DataFormValidationComponent with validation r…

81d355f

…ules and predefined options

elazzabi added 4 commits August 22, 2025 10:50

Add ValidatedFormTokenControl component to enhance array input valida…

b3b0c28

…tion with custom and required checks

Enhance array validation logic to ensure elements are only checked if…

382cb4c

… isValid elements is passed

Refactor array control to support internationalization and improve va…

203af53

…lue handling.

Add countries field to DataFormValidationComponent with validation ru…

a65e3b0

…les and predefined options

oandregal reviewed Aug 22, 2025

View reviewed changes

mirka reviewed Aug 22, 2025

View reviewed changes

This was referenced Sep 4, 2025

Field API: Validation #71500

Open

DataViews & DataForm iteration for WordPress 6.9 #70936

Closed

DataForm: Add a textarea control available for use with the text field type #71495

Merged

elazzabi added 2 commits September 10, 2025 14:22

Merge branch 'trunk' into add/elements-validation

538fc3a

Expose ValidatedFormTokenField from private API

8d5d551

oandregal reviewed Sep 11, 2025

View reviewed changes

packages/components/CHANGELOG.md Outdated Show resolved Hide resolved

Change changelog for components

75a0a5f

Co-authored-by: André <583546+oandregal@users.noreply.github.com>

elazzabi added 4 commits September 11, 2025 10:29

Call onInputChange after reseting the input

fe03b3d

Pass an onInputChange instead of onFocus

6ef2a57

Merge branch 'add/elements-validation' of https://github.com/elazzabi…

1a94d66

…/gutenberg into add/elements-validation

Remove validation for elements as it is replaced by control-level val…

f2e301d

…idation

Add documentation for elements

27536bc