@wordpress/components 30.2.1-next.0f6f9d12c.0 → 30.2.2-next.e256d081a.0

package/src/validated-form-controls/components/stories/combobox-control.story.tsx

@@ -35,6 +35,12 @@ export const Default: StoryObj< typeof ValidatedComboboxControl > = {
 					typeof ValidatedComboboxControl
 				>[ 'value' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedComboboxControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedComboboxControl
@@ -44,6 +50,17 @@ export const Default: StoryObj< typeof ValidatedComboboxControl > = {
 					setValue( newValue );
 					onChange?.( newValue );
 				} }
+				onValidate={ ( v ) => {
+					if ( v === 'a' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'Option A is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -56,10 +73,4 @@ Default.args = {
 		{ value: 'a', label: 'Option A (not allowed)' },
 		{ value: 'b', label: 'Option B' },
 	],
-	customValidator: ( value ) => {
-		if ( value === 'a' ) {
-			return 'Option A is not allowed.';
-		}
-		return undefined;
-	},
 };

package/src/validated-form-controls/components/stories/custom-select-control.story.tsx

@@ -35,6 +35,12 @@ export const Default: StoryObj< typeof ValidatedCustomSelectControl > = {
 					typeof ValidatedCustomSelectControl
 				>[ 'value' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedCustomSelectControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedCustomSelectControl
@@ -44,6 +50,17 @@ export const Default: StoryObj< typeof ValidatedCustomSelectControl > = {
 					setValue( newValue.selectedItem );
 					onChange?.( newValue );
 				} }
+				onValidate={ ( v ) => {
+					if ( v?.key === 'a' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'Option A is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -56,10 +73,4 @@ Default.args = {
 		{ key: 'a', name: 'Option A (not allowed)' },
 		{ key: 'b', name: 'Option B' },
 	],
-	customValidator: ( value ) => {
-		if ( value?.key === 'a' ) {
-			return 'Option A is not allowed.';
-		}
-		return undefined;
-	},
 };

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

@@ -46,6 +46,12 @@ export const Default: StoryObj< typeof ValidatedInputControl > = {
 			useState<
 				React.ComponentProps< typeof ValidatedInputControl >[ 'value' ]
 			>( '' );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedInputControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedInputControl
@@ -55,6 +61,17 @@ export const Default: StoryObj< typeof ValidatedInputControl > = {
 					setValue( newValue );
 					onChange?.( newValue, ...rest );
 				} }
+				onValidate={ ( v ) => {
+					if ( v?.toLowerCase() === 'error' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'The word "error" is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -63,12 +80,6 @@ Default.args = {
 	required: true,
 	label: 'Input',
 	help: 'The word "error" will trigger an error.',
-	customValidator: ( value ) => {
-		if ( value?.toLowerCase() === 'error' ) {
-			return 'The word "error" is not allowed.';
-		}
-		return undefined;
-	},
 };
 
 /**
@@ -83,6 +94,12 @@ export const Password: StoryObj< typeof ValidatedInputControl > = {
 				React.ComponentProps< typeof ValidatedInputControl >[ 'value' ]
 			>( '' );
 		const [ visible, setVisible ] = useState( false );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedInputControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedInputControl
@@ -105,6 +122,34 @@ export const Password: StoryObj< typeof ValidatedInputControl > = {
 					setValue( newValue );
 					onChange?.( newValue, ...rest );
 				} }
+				onValidate={ ( v ) => {
+					if ( ! /\d/.test( v ?? '' ) ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message:
+								'Password must include at least one number.',
+						} );
+						return;
+					}
+					if ( ! /[A-Z]/.test( v ?? '' ) ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message:
+								'Password must include at least one capital letter.',
+						} );
+						return;
+					}
+					if ( ! /[!@£$%^&*#]/.test( v ?? '' ) ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message:
+								'Password must include at least one symbol.',
+						} );
+						return;
+					}
+					setCustomValidity( undefined );
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -114,18 +159,6 @@ Password.args = {
 	label: 'Password',
 	help: 'Minimum 8 characters, include a number, capital letter, and symbol (!@£$%^&*#).',
 	minLength: 8,
-	customValidator: ( value ) => {
-		if ( ! /\d/.test( value ?? '' ) ) {
-			return 'Password must include at least one number.';
-		}
-		if ( ! /[A-Z]/.test( value ?? '' ) ) {
-			return 'Password must include at least one capital letter.';
-		}
-		if ( ! /[!@£$%^&*#]/.test( value ?? '' ) ) {
-			return 'Password must include at least one symbol.';
-		}
-		return undefined;
-	},
 };
 Password.argTypes = {
 	suffix: { control: false },

package/src/validated-form-controls/components/stories/number-control.story.tsx

@@ -37,6 +37,12 @@ export const Default: StoryObj< typeof ValidatedNumberControl > = {
 			useState<
 				React.ComponentProps< typeof ValidatedNumberControl >[ 'value' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedNumberControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedNumberControl
@@ -46,6 +52,17 @@ export const Default: StoryObj< typeof ValidatedNumberControl > = {
 					setValue( newValue );
 					onChange?.( newValue, ...rest );
 				} }
+				onValidate={ ( v ) => {
+					if ( v && parseInt( v.toString(), 10 ) % 2 !== 0 ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'Choose an even number.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -54,10 +71,4 @@ Default.args = {
 	required: true,
 	label: 'Number',
 	help: 'Odd numbers are not allowed.',
-	customValidator: ( value ) => {
-		if ( value && parseInt( value.toString(), 10 ) % 2 !== 0 ) {
-			return 'Choose an even number.';
-		}
-		return undefined;
-	},
 };

package/src/validated-form-controls/components/stories/overview.mdx

@@ -16,7 +16,7 @@ We are still gathering feedback and iterating. Please get in touch with `@WordPr
 
 Component APIs are the same as the underlying WordPress components, with the addition of some optional props:
 
-<ArgTypes of={ ValidatedInputControl } include={ [ 'required', 'markWhenOptional', 'customValidator' ] } />
+<ArgTypes of={ ValidatedInputControl } include={ [ 'required', 'markWhenOptional', 'onValidate', 'customValidity' ] } />
 
 ## Implementation
 

package/src/validated-form-controls/components/stories/overview.story.tsx

@@ -1,12 +1,14 @@
 /**
- * WordPress dependencies
+ * External dependencies
  */
-import { useState } from '@wordpress/element';
+import type { Meta, StoryObj } from '@storybook/react';
+import { expect, userEvent, waitFor, within } from '@storybook/test';
 
 /**
- * External dependencies
+ * WordPress dependencies
  */
-import type { Meta, StoryObj } from '@storybook/react';
+import { useRef, useCallback, useState } from '@wordpress/element';
+import { debounce } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -32,6 +34,18 @@ export const WithMultipleControls: Story = {
 	render: function Template() {
 		const [ text, setText ] = useState( '' );
 		const [ text2, setText2 ] = useState( '' );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedInputControl
+				>[ 'customValidity' ]
+			>( undefined );
+		const [ customValidity2, setCustomValidity2 ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedInputControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<>
@@ -40,12 +54,17 @@ export const WithMultipleControls: Story = {
 					required
 					value={ text }
 					help="The word 'error' will trigger an error."
-					customValidator={ ( value ) => {
+					onValidate={ ( value ) => {
 						if ( value?.toLowerCase() === 'error' ) {
-							return 'The word "error" is not allowed.';
+							setCustomValidity( {
+								type: 'invalid',
+								message: 'The word "error" is not allowed.',
+							} );
+						} else {
+							setCustomValidity( undefined );
 						}
-						return undefined;
 					} }
+					customValidity={ customValidity }
 					onChange={ ( value ) => setText( value ?? '' ) }
 				/>
 				<ValidatedInputControl
@@ -53,13 +72,18 @@ export const WithMultipleControls: Story = {
 					required
 					value={ text2 }
 					help="The word 'error' will trigger an error."
-					customValidator={ ( value ) => {
+					onValidate={ ( value ) => {
 						if ( value?.toLowerCase() === 'error' ) {
-							return 'The word "error" is not allowed.';
+							setCustomValidity2( {
+								type: 'invalid',
+								message: 'The word "error" is not allowed.',
+							} );
+						} else {
+							setCustomValidity2( undefined );
 						}
-						return undefined;
 					} }
 					onChange={ ( value ) => setText2( value ?? '' ) }
+					customValidity={ customValidity2 }
 				/>
 			</>
 		);
@@ -73,7 +97,12 @@ export const WithMultipleControls: Story = {
 export const WithHelpTextReplacement: Story = {
 	render: function Template() {
 		const [ text, setText ] = useState( '' );
-		const [ hasCustomError, setHasCustomError ] = useState( false );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedInputControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedInputControl
@@ -81,20 +110,181 @@ export const WithHelpTextReplacement: Story = {
 				required
 				value={ text }
 				help={
-					hasCustomError
+					customValidity
 						? undefined
 						: 'The word "error" is not allowed.'
 				}
-				customValidator={ ( value ) => {
+				onValidate={ ( value ) => {
 					if ( value?.toLowerCase() === 'error' ) {
-						setHasCustomError( true );
-						return 'The word "error" is not allowed.';
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'The word "error" is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
 					}
-					setHasCustomError( false );
-					return undefined;
 				} }
 				onChange={ ( value ) => setText( value ?? '' ) }
+				customValidity={ customValidity }
+			/>
+		);
+	},
+};
+
+/**
+ * To provide feedback from server-side validation, the `customValidity` prop can be used
+ * to show additional status indicators while waiting for the server response,
+ * and after the response is received.
+ *
+ * These indicators are intended for asynchronous validation calls that may take more than 1 second to complete.
+ * They may be unnecessary when responses are generally quick.
+ */
+export const AsyncValidation: StoryObj< typeof ValidatedInputControl > = {
+	render: function Template( { ...args } ) {
+		const [ text, setText ] = useState( '' );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedInputControl
+				>[ 'customValidity' ]
+			>( undefined );
+
+		const timeoutRef = useRef< ReturnType< typeof setTimeout > >();
+		const previousValidationValueRef = useRef< unknown >( '' );
+
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+		const debouncedValidate = useCallback(
+			debounce( ( v ) => {
+				if ( v === previousValidationValueRef.current ) {
+					return;
+				}
+
+				previousValidationValueRef.current = v;
+
+				setCustomValidity( {
+					type: 'validating',
+					message: 'Validating...',
+				} );
+
+				clearTimeout( timeoutRef.current );
+				timeoutRef.current = setTimeout( () => {
+					if ( v?.toString().toLowerCase() === 'error' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'The word "error" is not allowed.',
+						} );
+					} else {
+						setCustomValidity( {
+							type: 'valid',
+							message: 'Validated',
+						} );
+					}
+				}, 1500 );
+			}, 500 ),
+			[]
+		);
+
+		return (
+			<ValidatedInputControl
+				{ ...args }
+				value={ text }
+				onChange={ ( newValue ) => {
+					setText( newValue ?? '' );
+				} }
+				onValidate={ debouncedValidate }
+				customValidity={ customValidity }
 			/>
 		);
 	},
+	args: {
+		label: 'Text',
+		help: 'The word "error" will trigger an error asynchronously.',
+		required: true,
+	},
+};
+
+// Not exported - Only for testing purposes.
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+const AsyncValidationWithTest: StoryObj< typeof ValidatedInputControl > = {
+	...AsyncValidation,
+	play: async ( { canvasElement } ) => {
+		const canvas = within( canvasElement );
+		await userEvent.click( canvas.getByRole( 'textbox' ) );
+		await userEvent.type( canvas.getByRole( 'textbox' ), 'valid text', {
+			delay: 10,
+		} );
+		await userEvent.tab();
+
+		await waitFor(
+			() => {
+				expect( canvas.getByText( 'Validated' ) ).toBeVisible();
+			},
+			{ timeout: 2500 }
+		);
+
+		await new Promise( ( resolve ) => setTimeout( resolve, 500 ) );
+		await userEvent.clear( canvas.getByRole( 'textbox' ) );
+
+		// Should show validating state when transitioning from valid to invalid.
+		await waitFor(
+			() => {
+				expect( canvas.getByText( 'Validating...' ) ).toBeVisible();
+			},
+			{ timeout: 2500 }
+		);
+
+		await waitFor(
+			() => {
+				expect(
+					canvas.getByText( 'Please fill out this field.' )
+				).toBeVisible();
+			},
+			{ timeout: 2500 }
+		);
+
+		// Should not show validating state if there were no changes
+		// after a valid/invalid state was already shown.
+		await new Promise( ( resolve ) => setTimeout( resolve, 1500 ) );
+		await expect(
+			canvas.queryByText( 'Validating...' )
+		).not.toBeInTheDocument();
+
+		await userEvent.type( canvas.getByRole( 'textbox' ), 'e', {
+			delay: 10,
+		} );
+
+		// Should not show valid state if server has not yet responded.
+		await expect(
+			canvas.queryByText( 'Validated' )
+		).not.toBeInTheDocument();
+
+		// Should show validating state when transitioning from invalid to valid.
+		await waitFor(
+			() => {
+				expect( canvas.getByText( 'Validating...' ) ).toBeVisible();
+			},
+			{ timeout: 2500 }
+		);
+
+		await waitFor(
+			() => {
+				expect( canvas.getByText( 'Validated' ) ).toBeVisible();
+			},
+			{ timeout: 2500 }
+		);
+
+		await new Promise( ( resolve ) => setTimeout( resolve, 1000 ) );
+		await userEvent.type( canvas.getByRole( 'textbox' ), 'rror', {
+			delay: 10,
+		} );
+
+		await waitFor(
+			() => {
+				expect(
+					canvas.getByText( 'The word "error" is not allowed.' )
+				).toBeVisible();
+			},
+			{ timeout: 2500 }
+		);
+	},
 };

package/src/validated-form-controls/components/stories/radio-control.story.tsx

@@ -35,6 +35,12 @@ export const Default: StoryObj< typeof ValidatedRadioControl > = {
 					typeof ValidatedRadioControl
 				>[ 'selected' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedRadioControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedRadioControl
@@ -44,6 +50,17 @@ export const Default: StoryObj< typeof ValidatedRadioControl > = {
 					setSelected( value );
 					onChange?.( value );
 				} }
+				onValidate={ ( v ) => {
+					if ( v === 'b' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'Option B is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -56,10 +73,4 @@ Default.args = {
 		{ label: 'Option A', value: 'a' },
 		{ label: 'Option B (not allowed)', value: 'b' },
 	],
-	customValidator: ( value ) => {
-		if ( value === 'b' ) {
-			return 'Option B is not allowed.';
-		}
-		return undefined;
-	},
 };

package/src/validated-form-controls/components/stories/range-control.story.tsx

@@ -33,6 +33,12 @@ export const Default: StoryObj< typeof ValidatedRangeControl > = {
 			useState<
 				React.ComponentProps< typeof ValidatedRangeControl >[ 'value' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedRangeControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedRangeControl
@@ -42,6 +48,17 @@ export const Default: StoryObj< typeof ValidatedRangeControl > = {
 					setValue( newValue );
 					onChange?.( newValue );
 				} }
+				onValidate={ ( v ) => {
+					if ( v && v % 2 !== 0 ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'Choose an even number.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -52,10 +69,4 @@ Default.args = {
 	help: 'Odd numbers are not allowed.',
 	min: 0,
 	max: 20,
-	customValidator: ( value ) => {
-		if ( value && value % 2 !== 0 ) {
-			return 'Choose an even number.';
-		}
-		return undefined;
-	},
 };

package/src/validated-form-controls/components/stories/select-control.story.tsx

@@ -30,6 +30,12 @@ export default meta;
 export const Default: StoryObj< typeof ValidatedSelectControl > = {
 	render: function Template( { onChange, ...args } ) {
 		const [ value, setValue ] = useState( '' );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedSelectControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedSelectControl
@@ -39,6 +45,17 @@ export const Default: StoryObj< typeof ValidatedSelectControl > = {
 					setValue( newValue );
 					onChange?.( newValue );
 				} }
+				onValidate={ ( v ) => {
+					if ( v === '1' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'Option 1 is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -52,10 +69,4 @@ Default.args = {
 		{ value: '1', label: 'Option 1 (not allowed)' },
 		{ value: '2', label: 'Option 2' },
 	],
-	customValidator: ( value ) => {
-		if ( value === '1' ) {
-			return 'Option 1 is not allowed.';
-		}
-		return undefined;
-	},
 };

package/src/validated-form-controls/components/stories/text-control.story.tsx

@@ -30,6 +30,12 @@ export default meta;
 export const Default: StoryObj< typeof ValidatedTextControl > = {
 	render: function Template( { onChange, ...args } ) {
 		const [ value, setValue ] = useState( '' );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedTextControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedTextControl
@@ -39,6 +45,17 @@ export const Default: StoryObj< typeof ValidatedTextControl > = {
 					setValue( newValue );
 					onChange?.( newValue );
 				} }
+				onValidate={ ( v ) => {
+					if ( v?.toString().toLowerCase() === 'error' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'The word "error" is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -47,10 +64,4 @@ Default.args = {
 	required: true,
 	label: 'Text',
 	help: "The word 'error' will trigger an error.",
-	customValidator: ( value ) => {
-		if ( value?.toString().toLowerCase() === 'error' ) {
-			return 'The word "error" is not allowed.';
-		}
-		return undefined;
-	},
 };