DataForm: add `array` control #71136

elazzabi · 2025-08-08T10:53:30Z

This is a WIP

What?

This adds support for the array type in DataForm.

Why?

This field can be used for tags, categories, and others.

How?

Testing Instructions

Start Storybook and navigate to DataForm/Docs
Scroll down to the Tags section (see video below)

Testing Instructions for Keyboard

Screenshots or screencast

CleanShot.2025-08-08.at.11.51.00.mp4

github-actions · 2025-08-08T10:53:41Z

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 <[email protected]>
Co-authored-by: oandregal <[email protected]>
Co-authored-by: mirka <[email protected]>

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

github-actions · 2025-08-08T10:54:04Z

👋 Thanks for your first Pull Request and for helping build the future of Gutenberg and WordPress, @elazzabi! In case you missed it, we'd love to have you join us in our Slack community.

If you want to learn more about WordPress development in general, check out the Core Handbook full of helpful information.

oandregal · 2025-08-08T11:07:25Z

packages/dataviews/src/components/dataform/stories/index.story.tsx

+			{ value: 'javascript', label: 'JavaScript' },
+			{ value: 'react', label: 'React' },
+		],
+		__experimentalExpandOnFocus: true,


Does this need to be configurable? We can land this PR making this behavior the default in the component (without this prop) and only later revisit if we need to configure it.

We (in Woo) need this to be expanded on focus (hence the prop here to try it out in Storybook). However, I'm not sure if it's the default behavior we want 😅

oandregal · 2025-08-08T11:08:31Z

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

+	onChange,
+	hideLabelFromVision,
+}: DataFormControlProps< Item > ) {
+	const { id, label, placeholder, suggestions, ...extraProps } = field;


About ...extraProps: if we need a field to configure a UI component, we may want to come with a structured (and safer) way to do it.

The FormTokenField component accepts many props, I'm not sure where we should draw the line of "You can change this, but you can't change that". Which is the reason why I used the ...extraProps here. However, I'm open to have a structured object

If back compat concerns are at play here, we should probably keep component-level customization to a minimum at this time, and also keep web standard terminology in mind when naming the properties in the public-facing API. The next-generation DS component that would handle this array type field will either be a combobox or a multiple select, but FormTokenField props don't use web standard terminology for either pattern. We need to normalize the arbitrary/opinionated names into more standard ones (like the suggestions → elements rename that was done in 7094494), that ideally will not be weird regardless of whether we end up with a combobox or multiple select.

Perfect, that makes sense.

Keeping this in mind, I went ahead and added a few defaults here f48d7e0

Make the selection open on focus, by default.

Make sure the user can only select from the elements provided.

I think in the case of a multiselect, this makes sense as we want to see the possible options (open on focus), and we shouldn't be able to add new elements (ie, the validation function).

Let me know if that sounds good to you. I'll look into failing tests next

Sounds good to me!

packages/dataviews/src/types.ts

…y only

packages/dataviews/src/components/dataform/stories/index.story.tsx

packages/dataviews/src/types.ts

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

oandregal · 2025-08-12T06:22:19Z

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

+	);
+
+	// Custom validation function for FormTokenField
+	const validateInput = useCallback(


What if the array doesn't provide any elements? Users still need to be able to add values in that case:

Screen.Recording.2025-08-12.at.08.18.55.mov

We have a story for each field type. In the array story, can we add an example of field array without elements to make sure this case is testable?

Additionally, if there are no elements provided, we could improve the user experience by:

not displaying the suggestion list (__experimentalExpandOnFocus)

displaying the how to (__experimentalShowHowTo), so users know how to interact with the component

packages/dataviews/src/components/dataform/stories/index.story.tsx

oandregal · 2025-08-12T06:44:13Z

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

@@ -51,7 +53,7 @@ export function getControl< Item >(
 		return getControlByType( field.Edit );
 	}

-	if ( field.elements ) {


This is okay for now, it's how it's already working. I think a better approach would be to actually remove this from here and make every field definition absorb this (handle how they want to use or not use the elements information). Leaving this as feedback in case you are available to follow up on this in a separate PR, as it involves testing/making sure every field type works well for editing and filtering.

oandregal · 2025-08-12T06:45:50Z

Hi @elazzabi this is almost ready to merge, it only needs to address some edge cases. Thanks for continue to iterate on it. When you're ready, note that this also needs a changelog entry packages/dataviews/CHANGELOG.md (note the failing check).

…ements are present

packages/dataviews/CHANGELOG.md

packages/dataviews/src/components/dataform/stories/index.story.tsx

Co-authored-by: André <[email protected]>

oandregal · 2025-08-13T08:03:24Z

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

+	);
+
+	const onChangeControl = useCallback(
+		( tokens: ( string | { value: string } )[] ) => {


I'm trying to understand when the returned tokens can be an array of objects instead of strings. Unless I'm missing some context, I can't reproduce; every individual token is always a string. Can you confirm this? If so, can we simplify this to only handle strings?

That is because the onChange prop from FormTokenField expects that. I haven't been able to reproduce this too, as it's always strings, but changing that will raise a TypeScript error 😞

Ah, I missed that. It's all good, thanks for the context.

oandregal

Thanks for iterating on this one, Ahmed! I've left some minor comments, but this is working well otherwise. I'll merge when those are addressed.

oandregal · 2025-08-13T08:12:42Z

I discussed with Ahmed a follow-up we want to make: there are use cases where we want to prevent users from introducing new items, if there are elements provided. This will be a follow-up PR.

One way to make this work is by leveraging the validation mechanism:

[
  {
    // Array field that allows users to introduce new values.
    id: 'oneField',
    type: 'array',
    elements: [ /* ... */ ]
  },
  {
    // Array field that doesn't allow users to introduce new values.
    id: 'otherField',
    type: 'array',
    elements: [ /* ... */],
    isValid: {
      elements: true
    }
  }
]

oandregal · 2025-08-13T09:05:09Z

Congrats on your 1st contribution to Gutenberg, @elazzabi

elazzabi · 2025-08-13T13:21:31Z

Thank you for the reviews and help @oandregal 🙏

elazzabi added 5 commits August 8, 2025 11:43

Add suggestions to to type

645cf41

Add array dataform-controls

42707cd

Use array for the Edit prop when type is array

d8fabd6

Pass array to FORM_CONTROLS

e2f4bc7

Add tags to storybook

416badc

elazzabi requested a review from oandregal as a code owner August 8, 2025 10:53

github-actions bot added the First-time Contributor Pull request opened by a first-time contributor to Gutenberg repository label Aug 8, 2025

oandregal reviewed Aug 8, 2025

View reviewed changes

packages/dataviews/src/types.ts Outdated Show resolved Hide resolved

elazzabi added 5 commits August 8, 2025 14:55

Use elements instead of suggestions

7094494

Return by type instead of checking for elements

1d5ab6a

Update defaults to 1) Expand on focus, and 2) validate inputs in arra…

f48d7e0

…y only

Add a check to keep backward compatibility

a1f315f

Remove the how to by default

6a61e46

elazzabi commented Aug 11, 2025

View reviewed changes

packages/dataviews/src/components/dataform/stories/index.story.tsx Show resolved Hide resolved

oandregal reviewed Aug 12, 2025

View reviewed changes

packages/dataviews/src/types.ts Outdated Show resolved Hide resolved

oandregal reviewed Aug 12, 2025

View reviewed changes

packages/dataviews/src/dataform-controls/array.tsx Outdated Show resolved Hide resolved

oandregal reviewed Aug 12, 2025

View reviewed changes

packages/dataviews/src/components/dataform/stories/index.story.tsx Outdated Show resolved Hide resolved

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

oandregal reviewed Aug 12, 2025

View reviewed changes

oandregal changed the title ~~[WIP] Add type array implementation to DataForm and update storybook implementation~~ DataForm: add array control Aug 12, 2025

elazzabi added 3 commits August 12, 2025 10:17

remove extraprops

3ab76c0

Update categories for a better example

14a28cd

Update changelog

3b5aca8

elazzabi and others added 4 commits August 12, 2025 10:37

Move changelog to unreleased

20a5622

Remove validation, show helper text, and only expand on focus when el…

306d98c

…ements are present

Revert the addition of select to field type

666a2c1

Merge branch 'trunk' into add/array-to-dataform

9c8389a