@wordpress/components 30.1.0 → 30.2.0

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

@@ -15,7 +15,8 @@ import { ValidatedSelectControl } from '../select-control';
 import { formDecorator } from './story-utils';
 
 const meta: Meta< typeof ValidatedSelectControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedSelectControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedSelectControl',
+	id: 'components-validatedselectcontrol',
 	component: ValidatedSelectControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -29,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
@@ -38,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 }
 			/>
 		);
 	},
@@ -51,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

@@ -15,7 +15,8 @@ import { formDecorator } from './story-utils';
 import { ValidatedTextControl } from '../text-control';
 
 const meta: Meta< typeof ValidatedTextControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedTextControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedTextControl',
+	id: 'components-validatedtextcontrol',
 	component: ValidatedTextControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -29,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
@@ -38,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 }
 			/>
 		);
 	},
@@ -46,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

@@ -14,7 +14,8 @@ import { formDecorator } from './story-utils';
 import { ValidatedTextareaControl } from '../textarea-control';
 
 const meta: Meta< typeof ValidatedTextareaControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedTextareaControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedTextareaControl',
+	id: 'components-validatedtextareacontrol',
 	component: ValidatedTextareaControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -26,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
@@ -35,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 }
 			/>
 		);
 	},
@@ -43,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

@@ -15,7 +15,8 @@ import { formDecorator } from './story-utils';
 import { ValidatedToggleControl } from '../toggle-control';
 
 const meta: Meta< typeof ValidatedToggleControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedToggleControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedToggleControl',
+	id: 'components-validatedtogglecontrol',
 	component: ValidatedToggleControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -29,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
@@ -38,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 }
 			/>
 		);
 	},
@@ -46,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

@@ -16,7 +16,8 @@ import { ValidatedToggleGroupControl } from '../toggle-group-control';
 import { ToggleGroupControlOption } from '../../../toggle-group-control';
 
 const meta: Meta< typeof ValidatedToggleGroupControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedToggleGroupControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedToggleGroupControl',
+	id: 'components-validatedtogglegroupcontrol',
 	component: ValidatedToggleGroupControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -35,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
@@ -44,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 }
 			/>
 		);
 	},
@@ -57,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;
+	};
 };

package/src/validated-form-controls/control-with-error.tsx

@@ -2,7 +2,6 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
-import { error } from '@wordpress/icons';
 
 /**
  * External dependencies
@@ -18,8 +17,8 @@ import {
  * Internal dependencies
  */
 import { withIgnoreIMEEvents } from '../utils/with-ignore-ime-events';
-
-import Icon from '../icon';
+import type { ValidatedControlProps } from './components/types';
+import { ValidityIndicator } from './validity-indicator';
 
 function appendRequiredIndicator(
 	label: React.ReactNode,
@@ -61,7 +60,8 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 	{
 		required,
 		markWhenOptional,
-		customValidator,
+		onValidate,
+		customValidity,
 		getValidityTarget,
 		children,
 	}: {
@@ -74,12 +74,10 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 		 */
 		markWhenOptional?: boolean;
 		/**
-		 * A function that returns a custom validity message when applicable.
-		 *
-		 * This message will be applied to the element returned by `getValidityTarget`.
-		 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity
+		 * The callback to run when the input should be validated.
 		 */
-		customValidator?: () => string | void;
+		onValidate?: () => void;
+		customValidity?: ValidatedControlProps< unknown >[ 'customValidity' ];
 		/**
 		 * A function that returns the actual element on which the validity data should be applied.
 		 */
@@ -92,6 +90,13 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 	forwardedRef: React.ForwardedRef< HTMLDivElement >
 ) {
 	const [ errorMessage, setErrorMessage ] = useState< string | undefined >();
+	const [ statusMessage, setStatusMessage ] = useState<
+		| {
+				type: 'validating' | 'valid';
+				message?: string;
+		  }
+		| undefined
+	>();
 	const [ isTouched, setIsTouched ] = useState( false );
 
 	// Ensure that error messages are visible after user attemps to submit a form
@@ -111,13 +116,58 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 		};
 	} );
 
-	const validate = () => {
-		const message = customValidator?.();
+	useEffect( () => {
+		if ( ! isTouched ) {
+			return;
+		}
+
 		const validityTarget = getValidityTarget();
 
-		validityTarget?.setCustomValidity( message ?? '' );
-		setErrorMessage( validityTarget?.validationMessage );
-	};
+		if ( ! customValidity?.type ) {
+			validityTarget?.setCustomValidity( '' );
+			setErrorMessage( validityTarget?.validationMessage );
+			setStatusMessage( undefined );
+			return;
+		}
+
+		switch ( customValidity.type ) {
+			case 'validating': {
+				// Wait before showing a validating state.
+				const timer = setTimeout( () => {
+					setStatusMessage( {
+						type: 'validating',
+						message: customValidity.message,
+					} );
+				}, 1000 );
+
+				return () => clearTimeout( timer );
+			}
+			case 'valid': {
+				validityTarget?.setCustomValidity( '' );
+				setErrorMessage( validityTarget?.validationMessage );
+
+				setStatusMessage( {
+					type: 'valid',
+					message: customValidity.message,
+				} );
+				return;
+			}
+			case 'invalid': {
+				validityTarget?.setCustomValidity(
+					customValidity.message ?? ''
+				);
+				setErrorMessage( validityTarget?.validationMessage );
+
+				setStatusMessage( undefined );
+				return undefined;
+			}
+		}
+	}, [
+		isTouched,
+		customValidity?.type,
+		customValidity?.message,
+		getValidityTarget,
+	] );
 
 	const onBlur = ( event: React.FocusEvent< HTMLDivElement > ) => {
 		// Only consider "blurred from the component" if focus has fully left the wrapping div.
@@ -138,7 +188,7 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 				return;
 			}
 
-			validate();
+			onValidate?.();
 		}
 	};
 
@@ -148,7 +198,7 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 		// Only validate incrementally if the field has blurred at least once,
 		// or currently has an error message.
 		if ( isTouched || errorMessage ) {
-			validate();
+			onValidate?.();
 		}
 	};
 
@@ -156,7 +206,7 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 		// Ensures that custom validators are triggered when the user submits by pressing Enter,
 		// without ever blurring the control.
 		if ( event.key === 'Enter' ) {
-			validate();
+			onValidate?.();
 		}
 	};
 
@@ -180,15 +230,16 @@ function UnforwardedControlWithError< C extends React.ReactElement >(
 			} ) }
 			<div aria-live="polite">
 				{ errorMessage && (
-					<p className="components-validated-control__error">
-						<Icon
-							className="components-validated-control__error-icon"
-							icon={ error }
-							size={ 16 }
-							fill="currentColor"
-						/>
-						{ errorMessage }
-					</p>
+					<ValidityIndicator
+						type="invalid"
+						message={ errorMessage }
+					/>
+				) }
+				{ ! errorMessage && statusMessage && (
+					<ValidityIndicator
+						type={ statusMessage.type }
+						message={ statusMessage.message }
+					/>
 				) }
 			</div>
 		</div>

package/src/validated-form-controls/style.scss

@@ -45,7 +45,7 @@
 	pointer-events: none;
 }
 
-.components-validated-control__error {
+.components-validated-control__indicator {
 	display: flex;
 	align-items: flex-start;
 	gap: 4px;
@@ -53,17 +53,31 @@
 	font-family: $font-family-body;
 	font-size: 0.75rem;
 	line-height: 16px; // matches the icon size
-	color: $alert-red;
+	color: $components-color-gray-700;
 	animation:
-		components-validated-control__error-jump 0.2s
+		components-validated-control__indicator-jump 0.2s
 		cubic-bezier(0.68, -0.55, 0.27, 1.55);
+
+	&.is-invalid {
+		color: $alert-red;
+	}
+
+	&.is-valid {
+		color: color-mix(in srgb, $black 30%, $alert-green);
+	}
 }
 
-.components-validated-control__error-icon {
+.components-validated-control__indicator-icon {
 	flex-shrink: 0;
 }
 
-@keyframes components-validated-control__error-jump {
+.components-validated-control__indicator-spinner {
+	margin: 2px;
+	width: $grid-unit-15;
+	height: $grid-unit-15;
+}
+
+@keyframes components-validated-control__indicator-jump {
 	0% {
 		transform: translateY(-4px);
 		opacity: 0;

package/src/validated-form-controls/validity-indicator.tsx

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import clsx from 'clsx';
+
+/**
+ * WordPress dependencies
+ */
+import { error, published } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import Icon from '../icon';
+import Spinner from '../spinner';
+
+export function ValidityIndicator( {
+	type,
+	message,
+}: {
+	type: 'validating' | 'valid' | 'invalid';
+	message?: string;
+} ) {
+	const ICON = {
+		valid: published,
+		invalid: error,
+	};
+	return (
+		<p
+			className={ clsx(
+				'components-validated-control__indicator',
+				`is-${ type }`
+			) }
+		>
+			{ type === 'validating' ? (
+				<Spinner className="components-validated-control__indicator-spinner" />
+			) : (
+				<Icon
+					className="components-validated-control__indicator-icon"
+					icon={ ICON[ type ] }
+					size={ 16 }
+					fill="currentColor"
+				/>
+			) }
+			{ message }
+		</p>
+	);
+}

package/src/view/stories/index.story.tsx

@@ -10,11 +10,12 @@ import { View } from '..';
 
 const meta: Meta< typeof View > = {
 	component: View,
-	title: 'Components (Experimental)/View',
+	title: 'Components/View',
 	argTypes: {
 		as: { control: false },
 		children: { control: { type: 'text' } },
 	},
+	tags: [ 'status-experimental' ],
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },