Add support for elements validation in DataForm's array fields

packages/components/CHANGELOG.md

@@ -6,6 +6,10 @@
 
 -   `TextareaControl`: Add default resize: vertical rule ([#71736](https://github.com/WordPress/gutenberg/pull/71736)).
 
+### Internal
+
+-   Expose `ValidatedFormTokenField` via private APIs [#71194](https://github.com/WordPress/gutenberg/pull/71194)
+
 ## 30.4.0 (2025-09-17)
 
 ### Bug Fixes

packages/components/src/private-apis.ts

@@ -23,6 +23,7 @@ import {
 	ValidatedToggleControl,
 	ValidatedToggleGroupControl,
 } from './validated-form-controls';
+import { ValidatedFormTokenField } from './validated-form-controls/components/form-token-field';
 import { Picker } from './color-picker/picker';
 
 export const privateApis = {};
@@ -49,4 +50,5 @@ lock( privateApis, {
 	ValidatedTextareaControl,
 	ValidatedToggleControl,
 	ValidatedToggleGroupControl,
+	ValidatedFormTokenField,
 } );

packages/dataviews/CHANGELOG.md

@@ -5,6 +5,7 @@
 ### Features
 
 - Introduce a new `DataViewsPicker` component. [#70971](https://github.com/WordPress/gutenberg/pull/70971) and [#71836](https://github.com/WordPress/gutenberg/pull/71836).
+- DataForm: Add support for elements validation in array fields [#71194](https://github.com/WordPress/gutenberg/pull/71194)
 
 ### Bug Fixes
 
@@ -32,7 +33,7 @@
 - DataViews: support groupBy in the list layout. [#71548](https://github.com/WordPress/gutenberg/pull/71548)
 - DataForm: support validation in select control [#71665](https://github.com/WordPress/gutenberg/pull/71665)
 - DataForm: support validation in toggleGroup control. ([#71666](https://github.com/WordPress/gutenberg/pull/71666))
--  DataForm: Add object configuration support for Edit property with some options. ([#71582](https://github.com/WordPress/gutenberg/pull/71582))
+- DataForm: Add object configuration support for Edit property with some options. ([#71582](https://github.com/WordPress/gutenberg/pull/71582))
 - DataForm: Add summary field support for composed fields. ([#71614](https://github.com/WordPress/gutenberg/pull/71614))
 - DataForm: update radio control to support `required` and `custom` validation. [#71664](https://github.com/WordPress/gutenberg/pull/71664)
 

packages/dataviews/README.md

@@ -1235,6 +1235,7 @@ Example:
 Object that contains the validation rules for the field. If a rule is not met, the control will be marked as invalid and a message will be displayed.
 
 - `required`: boolean indicating whether the field is required or not.
+- `elements`: boolean restricting selection to the provided list of elements only. Used with the `array` field type.
 - `custom`: a function that validates a field's value. If the value is invalid, the function should return a string explaining why the value is invalid. Otherwise, the function must return null.
 
 Example:

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

@@ -525,6 +525,8 @@ const ValidationComponent = ( {
 		integer: number;
 		boolean: boolean;
 		customEdit: string;
+		categories: string[];
+		countries: string[];
 		password: string;
 		toggle?: boolean;
 		toggleGroup?: string;
@@ -541,6 +543,8 @@ const ValidationComponent = ( {
 		color: '#ff6600',
 		integer: 2,
 		boolean: true,
+		categories: [ 'astronomy' ],
+		countries: [ 'us' ],
 		customEdit: 'custom control',
 		password: 'secretpassword123',
 		toggle: undefined,
@@ -755,6 +759,41 @@ const ValidationComponent = ( {
 				custom: maybeCustomRule( customBooleanRule ),
 			},
 		},
+		{
+			id: 'categories',
+			type: 'array' as const,
+			label: 'Categories',
+			isValid: {
+				required,
+			},
+			elements: [
+				{ value: 'astronomy', label: 'Astronomy' },
+				{ value: 'book-review', label: 'Book review' },
+				{ value: 'event', label: 'Event' },
+				{ value: 'photography', label: 'Photography' },
+				{ value: 'travel', label: 'Travel' },
+			],
+		},
+		{
+			id: 'countries',
+			label: 'Countries Visited',
+			type: 'array' as const,
+			placeholder: 'Select countries',
+			description: 'Countries you have visited',
+			isValid: {
+				required,
+				elements: true,
+			},
+			elements: [
+				{ value: 'us', label: 'United States' },
+				{ value: 'ca', label: 'Canada' },
+				{ value: 'uk', label: 'United Kingdom' },
+				{ value: 'fr', label: 'France' },
+				{ value: 'de', label: 'Germany' },
+				{ value: 'jp', label: 'Japan' },
+				{ value: 'au', label: 'Australia' },
+			],
+		},
 		{
 			id: 'customEdit',
 			label: 'Custom Control',
@@ -812,6 +851,8 @@ const ValidationComponent = ( {
 			'color',
 			'integer',
 			'boolean',
+			'categories',
+			'countries',
 			'toggle',
 			'toggleGroup',
 			'password',

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

@@ -1,13 +1,22 @@
+/**
+ * External dependencies
+ */
+import deepMerge from 'deepmerge';
+
 /**
  * WordPress dependencies
  */
-import { FormTokenField } from '@wordpress/components';
-import { useCallback, useMemo } from '@wordpress/element';
+import { privateApis } from '@wordpress/components';
+import { useCallback, useMemo, useState } from '@wordpress/element';
+import { _n, sprintf } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
  */
 import type { DataFormControlProps } from '../types';
+import { unlock } from '../lock-unlock';
+
+const { ValidatedFormTokenField } = unlock( privateApis );
 
 export default function ArrayControl< Item >( {
 	data,
@@ -18,66 +27,154 @@ export default function ArrayControl< Item >( {
 	const { label, placeholder, elements, getValue, setValue } = field;
 	const value = getValue( { item: data } );
 
-	const findElementByValue = useCallback(
-		( suggestionValue: string ) => {
-			return elements?.find(
-				( suggestion ) => suggestion.value === suggestionValue
-			);
-		},
-		[ elements ]
-	);
+	const [ customValidity, setCustomValidity ] = useState<
+		| {
+				type: 'validating' | 'valid' | 'invalid';
+				message: string;
+		  }
+		| undefined
+	>( undefined );
 
-	const findElementByLabel = useCallback(
-		( suggestionLabel: string ) => {
-			return elements?.find(
-				( suggestion ) => suggestion.label === suggestionLabel
-			);
-		},
-		[ elements ]
-	);
-
-	// Ensure value is an array
-	const arrayValue = useMemo(
+	// Convert stored values to element objects for the token field
+	const arrayValueAsElements = useMemo(
 		() =>
 			Array.isArray( value )
 				? value.map( ( token ) => {
-						const tokenLabel = findElementByValue( token )?.label;
-						return tokenLabel || token;
+						const element = elements?.find(
+							( suggestion ) => suggestion.value === token
+						);
+						return element || { value: token, label: token };
 				  } )
 				: [],
-		[ value, findElementByValue ]
+		[ value, elements ]
 	);
 
-	const onChangeControl = useCallback(
-		( tokens: ( string | { value: string } )[] ) => {
-			// Convert TokenItem objects to strings
-			const stringTokens = tokens.map( ( token ) => {
-				if ( typeof token !== 'string' ) {
+	const validateTokens = useCallback(
+		( tokens: ( string | { value: string; label?: string } )[] ) => {
+			// Extract actual values from tokens for validation
+			const tokenValues = tokens.map( ( token ) => {
+				if ( typeof token === 'object' && 'value' in token ) {
 					return token.value;
 				}
+				return token;
+			} );
+
+			// First, check if elements validation is required and any tokens are invalid
+			if ( field.isValid?.elements && elements ) {
+				const invalidTokens = tokenValues.filter( ( tokenValue ) => {
+					return ! elements.some(
+						( element ) => element.value === tokenValue
+					);
+				} );
+
+				if ( invalidTokens.length > 0 ) {
+					setCustomValidity( {
+						type: 'invalid',
+						message: sprintf(
+							/* translators: %s: list of invalid tokens */
+							_n(
+								'Please select from the available options: %s is invalid.',
+								'Please select from the available options: %s are invalid.',
+								invalidTokens.length
+							),
+							invalidTokens.join( ', ' )
+						),
+					} );
+					return;
+				}
+			}
+
+			// Then check custom validation if provided.
+			if ( field.isValid?.custom ) {
+				const result = field.isValid?.custom?.(
+					deepMerge(
+						data,
+						setValue( {
+							item: data,
+							value: tokenValues,
+						} ) as Partial< Item >
+					),
+					field
+				);
+
+				if ( result ) {
+					setCustomValidity( {
+						type: 'invalid',
+						message: result,
+					} );
+					return;
+				}
+			}
 
-				const tokenByLabel = findElementByLabel( token );
+			// If no validation errors, clear custom validity
+			setCustomValidity( undefined );
+		},
+		[ elements, data, field, setValue ]
+	);
 
-				return tokenByLabel?.value || token;
+	const onChangeControl = useCallback(
+		( tokens: ( string | { value: string; label?: string } )[] ) => {
+			const valueTokens = tokens.map( ( token ) => {
+				if ( typeof token === 'object' && 'value' in token ) {
+					return token.value;
+				}
+				// If it's a string, it's either a new suggestion value or user input
+				return token;
 			} );
 
-			onChange( setValue( { item: data, value: stringTokens } ) );
+			onChange( setValue( { item: data, value: valueTokens } ) );
 		},
-		[ onChange, setValue, data, findElementByLabel ]
+		[ onChange, setValue, data ]
 	);
 
 	return (
-		<FormTokenField
+		<ValidatedFormTokenField
+			required={ !! field.isValid?.required }
+			onValidate={ validateTokens }
+			customValidity={ customValidity }
 			label={ hideLabelFromVision ? undefined : label }
-			value={ arrayValue }
+			value={ arrayValueAsElements }
 			onChange={ onChangeControl }
 			placeholder={ placeholder }
-			suggestions={
-				elements?.map( ( suggestion ) => suggestion.label ) ?? []
-			}
+			suggestions={ elements?.map( ( element ) => element.value ) }
+			__experimentalValidateInput={ ( token: string ) => {
+				// If elements validation is required, check if token is valid
+				if ( field.isValid?.elements && elements ) {
+					return elements.some(
+						( element ) =>
+							element.value === token || element.label === token
+					);
+				}
+
+				// For non-elements validation, allow all tokens
+				return true;
+			} }
 			__experimentalExpandOnFocus={ elements && elements.length > 0 }
-			__next40pxDefaultSize
-			__nextHasNoMarginBottom
+			__experimentalShowHowTo={ ! field.isValid?.elements }
+			displayTransform={ ( token: any ) => {
+				// For existing tokens (element objects), display their label
+				if ( typeof token === 'object' && 'label' in token ) {
+					return token.label;
+				}
+				// For suggestions (value strings), find the corresponding element and show its label
+				if ( typeof token === 'string' && elements ) {
+					const element = elements.find(
+						( el ) => el.value === token
+					);
+					return element?.label || token;
+				}
+				return token;
+			} }
+			__experimentalRenderItem={ ( { item }: { item: any } ) => {
+				// Custom rendering for suggestion items (item is a value string)
+				if ( typeof item === 'string' && elements ) {
+					const element = elements.find(
+						( el ) => el.value === item
+					);
+					return <span>{ element?.label || item }</span>;
+				}
+				return <span>{ item }</span>;
+			} }
 		/>
 	);
 }

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

@@ -59,14 +59,6 @@ const arrayFieldType: FieldTypeDefinition< any > = {
 				return __( 'Every value must be a string.' );
 			}
 
-			if ( field?.elements ) {
-				const validValues = field.elements.map( ( f ) => f.value );
-				if (
-					! value.every( ( v: any ) => validValues.includes( v ) )
-				) {
-					return __( 'Value must be one of the elements.' );
-				}
-			}
 			return null;
 		},
 	},