Add support for ValidatedFormTokenField by elazzabi · Pull Request #71350 · WordPress/gutenberg

elazzabi · 2025-08-26T09:53:24Z

https://github.com/WordPress/gutenberg/blob/trunk/CONTRIBUTING.md -->

What?

This adds support for the ValidatedArrayControl

Why?

This add a validated control to be used in different parts of the admin, including the country selector.

How?

CleanShot.2025-08-26.at.10.47.25.mp4

Testing Instructions

Get this PR locally
Start Storybook in dev mode
Visit ValidatedInputControl and scroll down to Array Control
Play with the component

Testing Instructions for Keyboard

Screenshots or screencast

Included above

…ndex file

…ation logic

github-actions · 2025-08-26T09:53:33Z

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: mirka <0mirka00@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.

elazzabi · 2025-08-26T09:54:48Z

cc @mirka

packages/dataviews/CHANGELOG.md

mirka

Thanks for working on this! 🙏

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

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

mirka · 2025-08-28T20:00:32Z

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

+			customValidity={ customValidity }
+			getValidityTarget={ getInputElement }
+		>
+			<div ref={ formTokenFieldRef }>


Certain props are passed down from ControlWithError to the inner control, so this simple div wrapper is not going to be sufficient. (I notice this wasn't mentioned anywhere in the documentation, so I'll add it at #71392.)

gutenberg/packages/components/src/validated-form-controls/control-with-error.tsx

Lines 223 to 231 in 775f0ce

{ cloneElement( children, {

label: appendRequiredIndicator(

children.props.label,

required,

markWhenOptional

),

onChange,

required,

} ) }

As for the ref passing, we can now make changes to the @wordpress/components components directly (unlike when I was working on the other controls 😅), so I think it would be cleaner to enhance FormTokenField itself so it forwards a ref to the underlying input. Right now FormTokenField doesn't take a ref at all. We should also enhance it so the required prop on FormTokenFieldwould also be passed down to the underlying input. This would allow us to be less hacky in this implementation. Could you try that?

Thank you for the review!

I looked into this, and this component is somewhat more challenging than the others. Since the checks for the required field only verify the input's value (i.e., not the tokens), it would always trigger an error, even when the field contains tokens.

I made some changes to disable the default required checks, but I'm unsure if this is the best approach or if you have other suggestions I can try.

Thank you!

I see! This has happened on two other components (ToggleGroupControl and CustomSelectControl), and I worked around it by using a hidden "delegate" element. At the time I thought it was hacky, but I later discovered that at least one other library uses a similar technique for all their validated form components, so I guess it isn't that weird.

I think we could try a normal <input type="text"> delegate here, since the built-in error message for required ("Please fill out this field.") is generic enough for FormTokenField. A <select multiple> delegate would be a better match for our array data type, but the built-in error message ("Please select an item in the list.") doesn't fit cases where FormTokenField can accept new items generated by the user.

Basically you append a hidden <input value={ hasTokens ? "has value" : "" }> or something so the required check reflects the selected token state. Does that make sense?

Gotcha! Thank you 🙏 I pushed changes in b6c9b91, let me know how that looks

mirka · 2025-08-28T20:36:37Z

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

+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';


I noticed some Sass variable handling is wrong in the stylesheet, so I'll fix it in #71391. With that in mind though, I think we'll need some error styles for FormTokenField as well, similar to what we have for ComboboxControl.

gutenberg/packages/components/src/validated-form-controls/style.scss

Lines 16 to 21 in 775f0ce

// For ComboboxControl

.components-combobox-control__suggestions-container:has(

input:user-invalid

):not(:has([aria-expanded="true"])) {

border-color: $alert-red;

}

I pushed some styles we can use in abc76d7.

…kenField

…mponents

mirka

Looking good! It's working as expected once the changes to FormTokenField itself are reverted.

packages/components/src/validated-form-controls/components/index.ts

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

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

mirka · 2025-09-09T15:34:46Z

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

I think we can revert the changes here in FormTokenField, since we're going with the delegate now. Passing down the required prop is actually problematic now, because it creates a required input that can never be filled 😄

I think only the required passing can be reverted, not the whole file. Done in ba0bd0f

I don't think the ref forwarding is strictly necessary for the functionality in this PR? It's more of an unrelated enhancement for FormTokenField at this point. No strong opinion though.

packages/components/src/form-token-field/types.ts

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

mirka · 2025-09-09T15:50:59Z

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

+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';


I pushed some styles we can use in abc76d7.

…gutenberg into add/array-form-control

elazzabi · 2025-09-09T16:11:38Z

Looks good after the recent changes, thank you for your help @mirka !

CleanShot.2025-09-09.at.17.09.45.mp4

mirka

Thanks for all the follow-ups! Looks great 🚀

mirka · 2025-09-10T09:56:50Z

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

I don't think the ref forwarding is strictly necessary for the functionality in this PR? It's more of an unrelated enhancement for FormTokenField at this point. No strong opinion though.

…gutenberg into add/array-form-control

elazzabi · 2025-09-10T10:13:45Z

Thank you, @mirka ! I agree, I pushed a change to remove the forwardref in 9494826 🙏

EDIT: Looks like I need at least these to make the testing pass 4603300

* Add ValidatedArrayControl component * Export ValidatedArrayControl component from validated-form-controls index file * Add ArrayControl story for ValidatedArrayControl component with validation logic * add changelog * Rename UnforwardedValidatedArrayControl to UnforwardedValidatedFormTokenField * Rename to form-token-field * Correct changelog place * Add a separate storybook page for the new component * Update FormTokenFieldProps interface to include 'required' prop * Refactor FormTokenField to use forwardRef and include 'required' prop * Enhance FormTokenField validation logic and refactor refs management * Replace HTML5 overriding with the delegate solution to match other components * Move changelog to unreleased * Add error styles * Move the export down for alphabetical order * revert changes in input-control story * Remove unnecessary use of name attribute * Revert passing required down * Add __experimentalExpandOnFocus for discoverability * Remove forward ref functionality * Add forwardedRef to div --------- Co-authored-by: elazzabi <elazzabi@git.wordpress.org> Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: oandregal <oandregal@git.wordpress.org>

elazzabi added 3 commits August 26, 2025 10:46

Add ValidatedArrayControl component

8490f04

Export ValidatedArrayControl component from validated-form-controls i…

02217c6

…ndex file

Add ArrayControl story for ValidatedArrayControl component with valid…

2726234

…ation logic

elazzabi requested a review from ajitbohra as a code owner August 26, 2025 09:53

elazzabi mentioned this pull request Aug 26, 2025

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

Merged

oandregal requested a review from mirka August 26, 2025 14:54

oandregal assigned elazzabi Aug 26, 2025

oandregal added [Type] Enhancement A suggestion for improvement. [Package] Components /packages/components labels Aug 26, 2025

oandregal self-requested a review August 26, 2025 14:58

add changelog

1818e44

oandregal reviewed Aug 28, 2025

View reviewed changes

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

mirka reviewed Aug 28, 2025

View reviewed changes

elazzabi added 4 commits August 29, 2025 14:58

Rename UnforwardedValidatedArrayControl to UnforwardedValidatedFormTo…

2b869a8

…kenField

Rename to form-token-field

6387d95

Correct changelog place

c948fb1

Add a separate storybook page for the new component

a45ebff

elazzabi changed the title ~~Add support for ValidatedArrayControl~~ Add support for ValidatedFormTokenField Aug 29, 2025

elazzabi added 3 commits September 1, 2025 15:58

Update FormTokenFieldProps interface to include 'required' prop

2825c27

Refactor FormTokenField to use forwardRef and include 'required' prop

b994646

Enhance FormTokenField validation logic and refactor refs management

e4e9965

This was referenced Sep 2, 2025

Add async validation support to FormTokenField #71428

Closed

ControlWithError: Add docs about cloned children #71392

Merged

oandregal mentioned this pull request Sep 4, 2025

Field API: Validation #71500

Closed

3 tasks

elazzabi and others added 4 commits September 8, 2025 14:58

Replace HTML5 overriding with the delegate solution to match other co…

b6c9b91

…mponents

Move changelog to unreleased

143e02b

Merge branch 'trunk' into add/array-form-control

83ebd47

Add error styles

abc76d7

mirka reviewed Sep 9, 2025

View reviewed changes

elazzabi added 6 commits September 9, 2025 16:57

Move the export down for alphabetical order

9b8e7cc

revert changes in input-control story

03cf1e0

Remove unnecessary use of name attribute

98a55a8

Revert passing required down

ba0bd0f

Add __experimentalExpandOnFocus for discoverability

200d263

Merge branch 'add/array-form-control' of https://github.com/elazzabi/…

d942d7c

…gutenberg into add/array-form-control

mirka approved these changes Sep 10, 2025

View reviewed changes

elazzabi added 3 commits September 10, 2025 11:08

Remove forward ref functionality

9494826

Merge branch 'trunk' into add/array-form-control

efc5174

Merge branch 'add/array-form-control' of https://github.com/elazzabi/…

5e0374d

…gutenberg into add/array-form-control

Add forwardedRef to div

4603300

mirka merged commit 0732dcd into WordPress:trunk Sep 10, 2025
68 checks passed

github-actions bot added this to the Gutenberg 21.7 milestone Sep 10, 2025

maxschmeling mentioned this pull request Oct 7, 2025

Add BlockCanvasCover SlotFill #72119

Closed

	{ cloneElement( children, {
	label: appendRequiredIndicator(
	children.props.label,
	required,
	markWhenOptional
	),
	onChange,
	required,
	} ) }

	// For ComboboxControl
	.components-combobox-control__suggestions-container:has(
	input:user-invalid
	):not(:has([aria-expanded="true"])) {
	border-color: $alert-red;
	}

Conversation

elazzabi commented Aug 26, 2025 • edited by oandregal Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Screenshots or screencast

Uh oh!

github-actions bot commented Aug 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

elazzabi commented Aug 26, 2025

Uh oh!

Uh oh!

mirka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

mirka Aug 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mirka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elazzabi commented Sep 9, 2025

Uh oh!

mirka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

elazzabi commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

elazzabi commented Aug 26, 2025 •

edited by oandregal

Loading

github-actions bot commented Aug 26, 2025 •

edited

Loading

mirka Aug 28, 2025 •

edited

Loading

elazzabi commented Sep 10, 2025 •

edited

Loading