@wordpress/components 30.9.0 → 31.0.0

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

@@ -3,6 +3,7 @@
  */
 import type { Meta, StoryObj } from '@storybook/react';
 import { expect, userEvent, waitFor, within } from '@storybook/test';
+import clsx from 'clsx';
 
 /**
  * WordPress dependencies
@@ -32,20 +33,8 @@ type Story = StoryObj< typeof ControlWithError >;
  */
 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 );
+		const [ text, setText ] = useState< string | undefined >( '' );
+		const [ text2, setText2 ] = useState< string | undefined >( '' );
 
 		return (
 			<>
@@ -54,36 +43,30 @@ export const WithMultipleControls: Story = {
 					required
 					value={ text }
 					help="The word 'error' will trigger an error."
-					onValidate={ ( value ) => {
-						if ( value?.toLowerCase() === 'error' ) {
-							setCustomValidity( {
-								type: 'invalid',
-								message: 'The word "error" is not allowed.',
-							} );
-						} else {
-							setCustomValidity( undefined );
-						}
-					} }
-					customValidity={ customValidity }
-					onChange={ ( value ) => setText( value ?? '' ) }
+					onChange={ setText }
+					customValidity={
+						text?.toLowerCase() === 'error'
+							? {
+									type: 'invalid',
+									message: 'The word "error" is not allowed.',
+							  }
+							: undefined
+					}
 				/>
 				<ValidatedInputControl
 					label="Text"
 					required
 					value={ text2 }
 					help="The word 'error' will trigger an error."
-					onValidate={ ( value ) => {
-						if ( value?.toLowerCase() === 'error' ) {
-							setCustomValidity2( {
-								type: 'invalid',
-								message: 'The word "error" is not allowed.',
-							} );
-						} else {
-							setCustomValidity2( undefined );
-						}
-					} }
-					onChange={ ( value ) => setText2( value ?? '' ) }
-					customValidity={ customValidity2 }
+					onChange={ setText2 }
+					customValidity={
+						text2?.toLowerCase() === 'error'
+							? {
+									type: 'invalid',
+									message: 'The word "error" is not allowed.',
+							  }
+							: undefined
+					}
 				/>
 			</>
 		);
@@ -96,37 +79,44 @@ export const WithMultipleControls: Story = {
  */
 export const WithHelpTextReplacement: Story = {
 	render: function Template() {
-		const [ text, setText ] = useState( '' );
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedInputControl
-				>[ 'customValidity' ]
-			>( undefined );
+		const [ text, setText ] = useState< string | undefined >( '' );
+		const isInvalid = text?.toLowerCase() === 'error';
 
 		return (
-			<ValidatedInputControl
-				label="Text"
-				required
-				value={ text }
-				help={
-					customValidity
-						? undefined
-						: 'The word "error" is not allowed.'
+			<>
+				<style>
+					{ `
+				.my-control:has(:invalid[data-validity-visible]) .my-control__help:not(.is-visible) {
+					display: none;
 				}
-				onValidate={ ( value ) => {
-					if ( value?.toLowerCase() === 'error' ) {
-						setCustomValidity( {
-							type: 'invalid',
-							message: 'The word "error" is not allowed.',
-						} );
-					} else {
-						setCustomValidity( undefined );
+				` }
+				</style>
+				<ValidatedInputControl
+					className="my-control"
+					label="Text"
+					required
+					value={ text }
+					help={
+						<span
+							className={ clsx(
+								'my-control__help',
+								! isInvalid && 'is-visible'
+							) }
+						>
+							The word &quot;error&quot; is not allowed.
+						</span>
 					}
-				} }
-				onChange={ ( value ) => setText( value ?? '' ) }
-				customValidity={ customValidity }
-			/>
+					onChange={ setText }
+					customValidity={
+						isInvalid
+							? {
+									type: 'invalid',
+									message: 'The word "error" is not allowed.',
+							  }
+							: undefined
+					}
+				/>
+			</>
 		);
 	},
 };
@@ -150,23 +140,19 @@ export const AsyncValidation: StoryObj< typeof ValidatedInputControl > = {
 			>( 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 ) {
+				if ( v === '' ) {
 					return;
 				}
 
-				previousValidationValueRef.current = v;
-
 				setCustomValidity( {
 					type: 'validating',
 					message: 'Validating...',
 				} );
 
-				clearTimeout( timeoutRef.current );
 				timeoutRef.current = setTimeout( () => {
 					if ( v?.toString().toLowerCase() === 'error' ) {
 						setCustomValidity( {
@@ -190,8 +176,10 @@ export const AsyncValidation: StoryObj< typeof ValidatedInputControl > = {
 				value={ text }
 				onChange={ ( newValue ) => {
 					setText( newValue ?? '' );
+					setCustomValidity( undefined );
+					clearTimeout( timeoutRef.current );
+					debouncedValidate( newValue );
 				} }
-				onValidate={ debouncedValidate }
 				customValidity={ customValidity }
 			/>
 		);
@@ -225,14 +213,6 @@ const AsyncValidationWithTest: StoryObj< typeof ValidatedInputControl > = {
 		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(
@@ -288,3 +268,38 @@ const AsyncValidationWithTest: StoryObj< typeof ValidatedInputControl > = {
 		);
 	},
 };
+
+/**
+ * Custom validity errors are effective immediately, even when they are not yet visible
+ * to the user. For example, in this form where the initial value is already invalid,
+ * the error message will be shown to the user once the submit button is clicked,
+ * even if the input has never been interacted with.
+ */
+export const CustomErrorsOnSubmit: StoryObj< typeof ValidatedInputControl > = {
+	args: {
+		label: 'Text',
+		required: true,
+		help: 'The word "error" will trigger an error.',
+	},
+	render: function Template( { ...args } ) {
+		const [ text, setText ] = useState< string | undefined >( 'error' );
+
+		return (
+			<>
+				<ValidatedInputControl
+					{ ...args }
+					value={ text }
+					onChange={ setText }
+					customValidity={
+						text === 'error'
+							? {
+									type: 'invalid',
+									message: 'The word "error" is not allowed.',
+							  }
+							: undefined
+					}
+				/>
+			</>
+		);
+	},
+};

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

@@ -35,32 +35,23 @@ export const Default: StoryObj< typeof ValidatedRadioControl > = {
 					typeof ValidatedRadioControl
 				>[ 'selected' ]
 			>();
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedRadioControl
-				>[ 'customValidity' ]
-			>( undefined );
 
 		return (
 			<ValidatedRadioControl
 				{ ...args }
 				selected={ selected }
-				onChange={ ( value ) => {
-					setSelected( value );
-					onChange?.( value );
-				} }
-				onValidate={ ( v ) => {
-					if ( v === 'b' ) {
-						setCustomValidity( {
-							type: 'invalid',
-							message: 'Option B is not allowed.',
-						} );
-					} else {
-						setCustomValidity( undefined );
-					}
+				onChange={ ( newValue ) => {
+					setSelected( newValue );
+					onChange?.( newValue );
 				} }
-				customValidity={ customValidity }
+				customValidity={
+					selected === 'b'
+						? {
+								type: 'invalid',
+								message: 'Option B is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -33,12 +33,6 @@ export const Default: StoryObj< typeof ValidatedRangeControl > = {
 			useState<
 				React.ComponentProps< typeof ValidatedRangeControl >[ 'value' ]
 			>();
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedRangeControl
-				>[ 'customValidity' ]
-			>( undefined );
 
 		return (
 			<ValidatedRangeControl
@@ -48,17 +42,14 @@ 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 }
+				customValidity={
+					value && value % 2 !== 0
+						? {
+								type: 'invalid',
+								message: 'Choose an even number.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -29,13 +29,7 @@ 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 );
+		const [ value, setValue ] = useState< string | undefined >( '' );
 
 		return (
 			<ValidatedSelectControl
@@ -45,17 +39,14 @@ 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 }
+				customValidity={
+					value === '1'
+						? {
+								type: 'invalid',
+								message: 'Option 1 is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -29,13 +29,10 @@ export default meta;
 
 export const Default: StoryObj< typeof ValidatedTextControl > = {
 	render: function Template( { onChange, ...args } ) {
-		const [ value, setValue ] = useState( '' );
-		const [ customValidity, setCustomValidity ] =
+		const [ value, setValue ] =
 			useState<
-				React.ComponentProps<
-					typeof ValidatedTextControl
-				>[ 'customValidity' ]
-			>( undefined );
+				React.ComponentProps< typeof ValidatedTextControl >[ 'value' ]
+			>( '' );
 
 		return (
 			<ValidatedTextControl
@@ -45,17 +42,14 @@ 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 }
+				customValidity={
+					value === 'error'
+						? {
+								type: 'invalid',
+								message: 'The word "error" is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -26,33 +26,29 @@ export default meta;
 
 export const Default: StoryObj< typeof ValidatedTextareaControl > = {
 	render: function Template( { onChange, ...args } ) {
-		const [ value, setValue ] = useState( '' );
-		const [ customValidity, setCustomValidity ] =
+		const [ value, setValue ] =
 			useState<
 				React.ComponentProps<
 					typeof ValidatedTextareaControl
-				>[ 'customValidity' ]
-			>( undefined );
+				>[ 'value' ]
+			>( '' );
 
 		return (
 			<ValidatedTextareaControl
 				{ ...args }
+				value={ value }
 				onChange={ ( newValue ) => {
 					setValue( newValue );
 					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 }
+				customValidity={
+					value?.toLowerCase() === 'error'
+						? {
+								type: 'invalid',
+								message: 'The word "error" is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -30,32 +30,23 @@ 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
 				{ ...args }
 				checked={ checked }
-				onChange={ ( value ) => {
-					setChecked( value );
-					onChange?.( value );
+				onChange={ ( newValue ) => {
+					setChecked( newValue );
+					onChange?.( newValue );
 				} }
-				onValidate={ ( v ) => {
-					if ( v ) {
-						setCustomValidity( {
-							type: 'invalid',
-							message: 'This toggle may not be enabled.',
-						} );
-					} else {
-						setCustomValidity( undefined );
-					}
-				} }
-				customValidity={ customValidity }
+				customValidity={
+					checked
+						? {
+								type: 'invalid',
+								message: 'This toggle may not be enabled.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -36,12 +36,6 @@ export const Default: StoryObj< typeof ValidatedToggleGroupControl > = {
 					typeof ValidatedToggleGroupControl
 				>[ 'value' ]
 			>( '1' );
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedToggleGroupControl
-				>[ 'customValidity' ]
-			>( undefined );
 
 		return (
 			<ValidatedToggleGroupControl
@@ -51,17 +45,14 @@ 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 }
+				customValidity={
+					value === '2'
+						? {
+								type: 'invalid',
+								message: 'Option 2 is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -10,36 +10,27 @@ import { forwardRef, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import TextControl from '../../text-control';
-import type { TextControlProps } from '../../text-control/types';
-
-type Value = TextControlProps[ 'value' ];
 
 const UnforwardedValidatedTextControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof TextControl >,
 		'__next40pxDefaultSize' | '__nextHasNoMarginBottom'
 	> &
-		ValidatedControlProps< Value >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLInputElement >
 ) => {
 	const validityTargetRef = useRef< HTMLInputElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.value );
 
 	return (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
@@ -47,10 +38,6 @@ const UnforwardedValidatedTextControl = (
 				__next40pxDefaultSize
 				__nextHasNoMarginBottom
 				ref={ mergedRefs }
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
 				{ ...restProps }
 			/>
 		</ControlWithError>

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

@@ -10,46 +10,33 @@ import { useMergeRefs } from '@wordpress/compose';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import TextareaControl from '../../textarea-control';
-import type { TextareaControlProps } from '../../textarea-control/types';
-
-type Value = TextareaControlProps[ 'value' ];
 
 const UnforwardedValidatedTextareaControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof TextareaControl >,
 		'__nextHasNoMarginBottom'
 	> &
-		ValidatedControlProps< Value >,
+		ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLTextAreaElement >
 ) => {
 	const validityTargetRef = useRef< HTMLTextAreaElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.value );
 
 	return (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<TextareaControl
 				__nextHasNoMarginBottom
 				ref={ mergedRefs }
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
 				{ ...restProps }
 			/>
 		</ControlWithError>