@wordpress/components 30.2.1-next.0f6f9d12c.0 → 30.2.1-next.f34ab90e9.0

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

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { useState } from '@wordpress/element';
+import { useRef, useCallback, useState } from '@wordpress/element';
 
 /**
  * External dependencies
@@ -14,6 +14,7 @@ import type { Meta, StoryObj } from '@storybook/react';
 import { ValidatedInputControl } from '..';
 import { formDecorator } from './story-utils';
 import type { ControlWithError } from '../../control-with-error';
+import { debounce } from '@wordpress/compose';
 
 const meta: Meta< typeof ControlWithError > = {
 	title: 'Components/Selection & Input/Validated Form Controls/Overview',
@@ -32,6 +33,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 +53,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 +71,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 +96,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 +109,100 @@ 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',
+							} );
+						}
+					},
+					// Mimics a random server response time.
+					// eslint-disable-next-line no-restricted-syntax
+					Math.random() < 0.5 ? 1500 : 300
+				);
+			}, 500 ),
+			[]
+		);
+
+		return (
+			<ValidatedInputControl
+				{ ...args }
+				value={ text }
+				onChange={ ( newValue ) => {
+					setText( newValue ?? '' );
+				} }
+				onValidate={ debouncedValidate }
+				customValidity={ customValidity }
+			/>
+		);
+	},
+};
+AsyncValidation.args = {
+	label: 'Text',
+	help: 'The word "error" will trigger an error asynchronously.',
+	required: true,
+};

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;
-	},
 };

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

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

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

@@ -30,6 +30,12 @@ export default meta;
 export const Default: StoryObj< typeof ValidatedToggleControl > = {
 	render: function Template( { onChange, ...args } ) {
 		const [ checked, setChecked ] = useState( false );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedToggleControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedToggleControl
@@ -39,6 +45,17 @@ export const Default: StoryObj< typeof ValidatedToggleControl > = {
 					setChecked( value );
 					onChange?.( value );
 				} }
+				onValidate={ ( v ) => {
+					if ( v ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'This toggle may not be enabled.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -47,10 +64,4 @@ Default.args = {
 	required: true,
 	label: 'Toggle',
 	help: 'This toggle may neither be enabled nor disabled.',
-	customValidator: ( value ) => {
-		if ( value ) {
-			return 'This toggle may not be enabled.';
-		}
-		return undefined;
-	},
 };

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

@@ -36,6 +36,12 @@ export const Default: StoryObj< typeof ValidatedToggleGroupControl > = {
 					typeof ValidatedToggleGroupControl
 				>[ 'value' ]
 			>( '1' );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedToggleGroupControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedToggleGroupControl
@@ -45,6 +51,17 @@ export const Default: StoryObj< typeof ValidatedToggleGroupControl > = {
 					setValue( newValue );
 					onChange?.( newValue );
 				} }
+				onValidate={ ( v ) => {
+					if ( v === '2' ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'Option 2 is not allowed.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -58,10 +75,4 @@ Default.args = {
 		<ToggleGroupControlOption value="2" key="2" label="Option 2" />,
 	],
 	help: 'Selecting option 2 will trigger an error.',
-	customValidator: ( value ) => {
-		if ( value === '2' ) {
-			return 'Option 2 is not allowed.';
-		}
-		return undefined;
-	},
 };

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

@@ -17,7 +17,8 @@ type Value = TextControlProps[ 'value' ];
 const UnforwardedValidatedTextControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedTextControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<TextControl

package/src/validated-form-controls/components/textarea-control.tsx

@@ -17,7 +17,8 @@ type Value = TextareaControlProps[ 'value' ];
 const UnforwardedValidatedTextareaControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedTextareaControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<TextareaControl

package/src/validated-form-controls/components/toggle-control.tsx

@@ -19,7 +19,8 @@ type Value = ToggleControlProps[ 'checked' ];
 const UnforwardedValidatedToggleControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -46,9 +47,10 @@ const UnforwardedValidatedToggleControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<ToggleControl

package/src/validated-form-controls/components/toggle-group-control.tsx

@@ -16,7 +16,8 @@ type Value = ToggleGroupControlProps[ 'value' ];
 const UnforwardedValidatedToggleGroupControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -37,9 +38,10 @@ const UnforwardedValidatedToggleGroupControl = (
 			<ControlWithError
 				required={ required }
 				markWhenOptional={ markWhenOptional }
-				customValidator={ () => {
-					return customValidator?.( valueRef.current );
+				onValidate={ () => {
+					return onValidate?.( valueRef.current );
 				} }
+				customValidity={ customValidity }
 				getValidityTarget={ () => validityTargetRef.current }
 			>
 				<ToggleGroupControl

package/src/validated-form-controls/components/types.ts

@@ -10,19 +10,28 @@ export type ValidatedControlProps< V > = {
 	 */
 	markWhenOptional?: boolean;
 	/**
-	 * A function that returns a custom validity message when applicable. This error message will be applied to the
-	 * underlying element using the native [`setCustomValidity()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity).
-	 * This means the custom validator will be run _in addition_ to any other HTML attribute-based validation, and
-	 * will be prioritized over any existing validity messages dictated by the HTML attributes.
-	 * An empty string or `undefined` return value will clear any existing custom validity message.
+	 * Optional callback to run when the input should be validated. Use this to set
+	 * a `customValidity` as necessary.
 	 *
-	 * Make sure you don't programatically pass a value (such as an initial value) to the control component
-	 * that fails this validator, because the validator will only run for user-initiated changes.
+	 * Always prefer using standard HTML attributes like `required` and `min`/`max` over
+	 * custom validators when possible, as they are simpler and have localized error messages built in.
+	 */
+	onValidate?: ( currentValue: V ) => void;
+	/**
+	 * Show a custom message based on the validation status.
 	 *
-	 * Always prefer using standard HTML attributes like `required` and `min`/`max` over custom validators
-	 * when possible, as they are simpler and have localized error messages built in.
+	 * - When `type` is `invalid`, the message will be applied to the underlying element using the
+	 * native [`setCustomValidity()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity).
+	 * This means the custom message will be prioritized over any existing validity messages
+	 * triggered by HTML attribute-based validation.
+	 * - When `type` is `validating` or `valid`, the custom validity message of the underlying element
+	 * will be cleared. If there are no remaining validity messages triggered by HTML attribute-based validation,
+	 * the message will be presented as a status indicator rather than an error. These indicators are intended
+	 * for asynchronous validation calls that may take more than 1 second to complete.
+	 * Otherwise, custom errors can simply be cleared by setting the `customValidity` prop to `undefined`.
 	 */
-	// TODO: Technically, we could add an optional `customValidity` string prop so the consumer can set
-	// an error message at any point in time. We should wait until we have a use case though.
-	customValidator?: ( currentValue: V ) => string | void;
+	customValidity?: {
+		type: 'validating' | 'valid' | 'invalid';
+		message: string;
+	};
 };