@wordpress/dataviews 10.0.1-next.ff1cebbba.0 → 10.1.0

package/src/test/use-form-validity.ts

@@ -0,0 +1,546 @@
+/**
+ * External dependencies
+ */
+import { renderHook, waitFor } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { useFormValidity } from '../hooks';
+import type { Field } from '../types';
+
+describe( 'useFormValidity', () => {
+	describe( 'fields', () => {
+		it( 'can override the defaults', () => {
+			const item = { id: 1, order: 'd' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'order',
+					type: 'integer',
+					elements: [
+						{ value: 'a', label: 'A' },
+						{ value: 'b', label: 'B' },
+					],
+					isValid: {
+						elements: false,
+						custom: () => null, // Overrides the validation provided for integer types.
+					},
+				},
+			];
+			const form = { fields: [ 'order' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+
+		it( 'not in the form are ignored', () => {
+			const item = { id: 1, valid_order: 2, invalid_order: 'd' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'valid_order',
+					type: 'integer',
+				},
+				{
+					id: 'invalid_order',
+					type: 'integer',
+				},
+			];
+			const form = { fields: [ 'valid_order' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+
+		it( 'with children are checked for validity', () => {
+			const item = { id: 1, order: undefined };
+			const fields: Field< {} >[] = [
+				{
+					id: 'order',
+					type: 'integer',
+					isValid: {
+						required: true,
+					},
+				},
+			];
+			const form = {
+				fields: [ { id: 'combinedField', children: [ 'order' ] } ],
+			};
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( {
+				combinedField: {
+					children: {
+						order: {
+							required: { type: 'invalid' },
+						},
+					},
+				},
+			} );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'without children but defined as objects are checked for validity', () => {
+			const item = { id: 1, order: undefined };
+			const fields: Field< {} >[] = [
+				{
+					id: 'order',
+					type: 'integer',
+					isValid: {
+						required: true,
+					},
+				},
+			];
+			const form = {
+				fields: [ { id: 'order' } ],
+			};
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( {
+				order: {
+					required: { type: 'invalid' },
+				},
+			} );
+			expect( isValid ).toBe( false );
+		} );
+	} );
+
+	describe( 'isValid.required', () => {
+		const REQUIRED_MESSAGE = {
+			required: { type: 'invalid' },
+		};
+
+		it( 'is valid when validity object only contains type:valid messages', async () => {
+			const item = { id: 1, title: 'Valid Title', status: 'published' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'title',
+					type: 'text',
+					isValid: {
+						custom: async () =>
+							await new Promise( ( resolve ) =>
+								setTimeout( resolve, 5 )
+							).then( () => null ),
+					},
+				},
+				{
+					id: 'status',
+					type: 'text',
+					isValid: {
+						custom: async () =>
+							await new Promise( ( resolve ) =>
+								setTimeout( resolve, 5 )
+							).then( () => null ),
+					},
+				},
+			];
+			const form = { fields: [ 'title', 'status' ] };
+			const { result } = renderHook( () =>
+				useFormValidity( item, fields, form )
+			);
+
+			await waitFor( () => {
+				expect( result.current ).toEqual( {
+					validity: {
+						title: {
+							custom: { type: 'valid', message: 'Valid' },
+						},
+						status: {
+							custom: { type: 'valid', message: 'Valid' },
+						},
+					},
+					isValid: true,
+				} );
+			} );
+		} );
+
+		it( 'array is invalid when required but empty', () => {
+			const item = { id: 1, tags: [] };
+			const fields: Field< {} >[] = [
+				{
+					id: 'tags',
+					type: 'array',
+					isValid: {
+						required: true,
+					},
+				},
+			];
+			const form = { fields: [ 'tags' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( REQUIRED_MESSAGE );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'array is invalid when required but not an array', () => {
+			const item = { id: 1, tags: null };
+			const fields: Field< {} >[] = [
+				{
+					id: 'tags',
+					type: 'array',
+					isValid: {
+						required: true,
+					},
+				},
+			];
+			const form = { fields: [ 'tags' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( REQUIRED_MESSAGE );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'array is valid when required and has values', () => {
+			const item = { id: 1, tags: [ 'tag1', 'tag2' ] };
+			const fields: Field< {} >[] = [
+				{
+					id: 'tags',
+					type: 'array',
+					isValid: {
+						required: true,
+					},
+				},
+			];
+			const form = { fields: [ 'tags' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+	} );
+
+	describe( 'isValid.elements', () => {
+		const ELEMENTS_MESSAGE = {
+			elements: {
+				type: 'invalid',
+				message: 'Value must be one of the elements.',
+			},
+		};
+		it( 'untyped is invalid if value is not one of the elements', () => {
+			const item = { id: 1, author: 'not-in-elements' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'author',
+					elements: [
+						{ value: 'jane', label: 'Jane' },
+						{ value: 'john', label: 'John' },
+					],
+				},
+			];
+			const form = { fields: [ 'author' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.author ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'text is valid when value is one of the elements', () => {
+			const item = { id: 1, status: 'published' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'status',
+					type: 'text',
+					elements: [
+						{ value: 'draft', label: 'Draft' },
+						{ value: 'published', label: 'Published' },
+					],
+					isValid: {
+						elements: true,
+					},
+				},
+			];
+			const form = { fields: [ 'status' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+
+		it( 'text is invalid when value is not one of the elements', () => {
+			const item = { id: 1, status: 'invalid-status' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'status',
+					type: 'text',
+					elements: [
+						{ value: 'draft', label: 'Draft' },
+						{ value: 'published', label: 'Published' },
+					],
+					isValid: {
+						elements: true,
+					},
+				},
+			];
+			const form = { fields: [ 'status' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.status ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'integer is valid when value is one of the elements', () => {
+			const item = { id: 1, priority: 2 };
+			const fields: Field< {} >[] = [
+				{
+					id: 'priority',
+					type: 'integer',
+					elements: [
+						{ value: 1, label: 'Low' },
+						{ value: 2, label: 'Medium' },
+						{ value: 3, label: 'High' },
+					],
+					isValid: {
+						elements: true,
+					},
+				},
+			];
+			const form = { fields: [ 'priority' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+
+		it( 'integer is invalid when value is not one of the elements', () => {
+			const item = { id: 1, priority: 5 };
+			const fields: Field< {} >[] = [
+				{
+					id: 'priority',
+					type: 'integer',
+					elements: [
+						{ value: 1, label: 'Low' },
+						{ value: 2, label: 'Medium' },
+						{ value: 3, label: 'High' },
+					],
+					isValid: {
+						elements: true,
+					},
+				},
+			];
+			const form = { fields: [ 'priority' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.priority ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'number is invalid if value is not one of the elements', () => {
+			const item = { id: 1, price: 4.5 };
+			const fields: Field< {} >[] = [
+				{
+					id: 'price',
+					type: 'number',
+					elements: [
+						{ value: 1.5, label: 'Bronze' },
+						{ value: 2.5, label: 'Silver' },
+					],
+				},
+			];
+			const form = { fields: [ 'price' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.price ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'array is valid if all items are part of the elements', () => {
+			const item = { id: 1, tags: [ 'red', 'blue' ] };
+			const fields: Field< {} >[] = [
+				{
+					id: 'tags',
+					type: 'array',
+					elements: [
+						{ value: 'red', label: 'Red' },
+						{ value: 'blue', label: 'Blue' },
+						{ value: 'green', label: 'Green' },
+					],
+				},
+			];
+			const form = { fields: [ 'tags' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+
+		it( 'array is invalid when not all items are part of the elements', () => {
+			const item = { id: 1, tags: [ 'red', 'yellow' ] };
+			const fields: Field< {} >[] = [
+				{
+					id: 'tags',
+					type: 'array',
+					elements: [
+						{ value: 'red', label: 'Red' },
+						{ value: 'blue', label: 'Blue' },
+						{ value: 'green', label: 'Green' },
+					],
+				},
+			];
+			const form = { fields: [ 'tags' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( ELEMENTS_MESSAGE );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'array is invalid when value is not an array', () => {
+			const item = { id: 1, tags: 'not-an-array' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'tags',
+					type: 'array',
+					elements: [
+						{ value: 'red', label: 'Red' },
+						{ value: 'blue', label: 'Blue' },
+					],
+					isValid: {
+						custom: () => null, // Disable to make sure the only validation triggered is elements
+					},
+				},
+			];
+			const form = { fields: [ 'tags' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.tags ).toEqual( {
+				elements: {
+					type: 'invalid',
+					message: 'Value must be an array.',
+				},
+			} );
+			expect( isValid ).toBe( false );
+		} );
+	} );
+
+	describe( 'isValid.custom', () => {
+		it( 'integer is valid if value is integer', () => {
+			const item = { id: 1, order: 2, title: 'hi' };
+			const fields: Field< {} >[] = [
+				{
+					type: 'integer',
+					id: 'order',
+				},
+			];
+			const form = { fields: [ 'order' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+
+		it( 'integer is invalid if value is not integer when not empty', () => {
+			const item = { id: 1, order: 'd' };
+			const fields: Field< {} >[] = [
+				{
+					id: 'order',
+					type: 'integer',
+				},
+			];
+			const form = { fields: [ 'order' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.order ).toEqual( {
+				custom: {
+					type: 'invalid',
+					message: 'Value must be an integer.',
+				},
+			} );
+			expect( isValid ).toBe( false );
+		} );
+
+		it( 'number is valid if value is finite', () => {
+			const item = { id: 1, price: 2.5 };
+			const fields: Field< {} >[] = [
+				{
+					id: 'price',
+					type: 'number',
+				},
+			];
+			const form = { fields: [ 'price' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity ).toEqual( undefined );
+			expect( isValid ).toBe( true );
+		} );
+
+		it( 'number is invalid if value is not finite when not empty', () => {
+			const item = { id: 1, price: Number.NaN };
+			const fields: Field< {} >[] = [
+				{
+					id: 'price',
+					type: 'number',
+				},
+			];
+			const form = { fields: [ 'price' ] };
+			const {
+				result: {
+					current: { validity, isValid },
+				},
+			} = renderHook( () => useFormValidity( item, fields, form ) );
+			expect( validity?.price ).toEqual( {
+				custom: {
+					type: 'invalid',
+					message: 'Value must be a number.',
+				},
+			} );
+			expect( isValid ).toBe( false );
+		} );
+	} );
+} );

package/src/types/dataform.ts

@@ -1,7 +1,7 @@
 /**
  * Internal dependencies
  */
-import type { Field } from './field-api';
+import type { Field, FieldValidity } from './field-api';
 
 /**
  * DataForm layouts.
@@ -130,11 +130,15 @@ export interface DataFormProps< Item > {
 	fields: Field< Item >[];
 	form: Form;
 	onChange: ( value: Record< string, any > ) => void;
+	validity?: FormValidity;
 }
 
+export type FormValidity = Record< string, FieldValidity > | undefined;
+
 export interface FieldLayoutProps< Item > {
 	data: Item;
 	field: FormField;
 	onChange: ( value: any ) => void;
 	hideLabelFromVision?: boolean;
+	validity?: FieldValidity;
 }

package/src/types/dataviews.ts

@@ -58,7 +58,17 @@ export interface NormalizedFilter {
 	/**
 	 * The list of options to pick from when using the field as a filter.
 	 */
-	elements: Option[];
+	elements?: Option[];
+
+	/**
+	 * Retrieval function to get the elements.
+	 */
+	getElements?: () => Promise< Option[] >;
+
+	/**
+	 * Whether the filter has elements.
+	 */
+	hasElements: boolean;
 
 	/**
 	 * Is a single selection filter.
@@ -332,7 +342,7 @@ export interface ActionModal< Item > extends ActionBase< Item > {
 	/**
 	 * The header of the modal.
 	 */
-	modalHeader?: string;
+	modalHeader?: string | ( ( items: Item[] ) => string );
 
 	/**
 	 * The size of the modal.

package/src/types/field-api.ts

@@ -151,7 +151,12 @@ export type FieldTypeDefinition< Item > = {
 export type Rules< Item > = {
 	required?: boolean;
 	elements?: boolean;
-	custom?: ( item: Item, field: NormalizedField< Item > ) => null | string;
+	custom?:
+		| ( ( item: Item, field: NormalizedField< Item > ) => null | string )
+		| ( (
+				item: Item,
+				field: NormalizedField< Item >
+		  ) => Promise< null | string > );
 };
 
 /**
@@ -276,6 +281,11 @@ export type Field< Item > = {
 	 */
 	elements?: Option[];
 
+	/**
+	 * Retrieval function for elements.
+	 */
+	getElements?: () => Promise< Option[] >;
+
 	/**
 	 * Filter config for the field.
 	 */
@@ -307,6 +317,7 @@ export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
 	setValue: ( args: { item: Item; value: any } ) => DeepPartial< Item >;
 	render: ComponentType< DataViewRenderFieldProps< Item > >;
 	Edit: ComponentType< DataFormControlProps< Item > > | null;
+	hasElements: boolean;
 	sort: ( a: Item, b: Item, direction: SortDirection ) => number;
 	isValid: Rules< Item >;
 	enableHiding: boolean;
@@ -320,6 +331,22 @@ export type NormalizedField< Item > = Omit< Field< Item >, 'Edit' > & {
  */
 export type Fields< Item > = Field< Item >[];
 
+export type FieldValidity = {
+	required?: {
+		type: 'valid' | 'invalid' | 'validating';
+		message?: string;
+	};
+	elements?: {
+		type: 'valid' | 'invalid' | 'validating';
+		message: string;
+	};
+	custom?: {
+		type: 'valid' | 'invalid' | 'validating';
+		message: string;
+	};
+	children?: Record< string, FieldValidity >;
+};
+
 export type DataFormControlProps< Item > = {
 	data: Item;
 	field: NormalizedField< Item >;
@@ -331,6 +358,10 @@ export type DataFormControlProps< Item > = {
 	 * Used by DataViews filters to determine which control to render based on the operator type.
 	 */
 	operator?: Operator;
+	/**
+	 * Validity information for the field, if any.
+	 */
+	validity?: FieldValidity;
 	/**
 	 * Configuration object for the control.
 	 */

package/src/utils/has-elements.ts

@@ -0,0 +1,11 @@
+/**
+ * Internal dependencies
+ */
+import type { Field } from '../types/field-api';
+
+export default function hasElements< Item >( field: Field< Item > ): boolean {
+	return (
+		( Array.isArray( field.elements ) && field.elements.length > 0 ) ||
+		typeof field.getElements === 'function'
+	);
+}

package/src/utils/normalize-fields.ts

@@ -20,6 +20,7 @@ import {
 	OPERATOR_BETWEEN,
 	SINGLE_SELECTION_OPERATORS,
 } from '../constants';
+import hasElements from './has-elements';
 
 const getValueFromId =
 	( id: string ) =>
@@ -81,7 +82,7 @@ function getFilterBy< Item >(
 		);
 
 		// The `between` operator is not supported when elements are provided.
-		if ( field.elements && operators.includes( OPERATOR_BETWEEN ) ) {
+		if ( hasElements( field ) && operators.includes( OPERATOR_BETWEEN ) ) {
 			operators = operators.filter(
 				( operator ) => operator !== OPERATOR_BETWEEN
 			);
@@ -119,7 +120,10 @@ function getFilterBy< Item >(
 
 	let defaultOperators = fieldTypeDefinition.filterBy.defaultOperators;
 	// The `between` operator is not supported when elements are provided.
-	if ( field.elements && defaultOperators.includes( OPERATOR_BETWEEN ) ) {
+	if (
+		hasElements( field ) &&
+		defaultOperators.includes( OPERATOR_BETWEEN )
+	) {
 		defaultOperators = defaultOperators.filter(
 			( operator ) => operator !== OPERATOR_BETWEEN
 		);
@@ -188,6 +192,7 @@ export default function normalizeFields< Item >(
 			sort,
 			isValid,
 			Edit,
+			hasElements: hasElements( field ),
 			enableHiding: field.enableHiding ?? true,
 			enableSorting:
 				field.enableSorting ??