@wordpress/components 30.1.0 → 30.2.0

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

@@ -15,7 +15,8 @@ import { ValidatedCheckboxControl } from '../checkbox-control';
 import { formDecorator } from './story-utils';
 
 const meta: Meta< typeof ValidatedCheckboxControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedCheckboxControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedCheckboxControl',
+	id: 'components-validatedcheckboxcontrol',
 	component: ValidatedCheckboxControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -31,6 +32,12 @@ export default meta;
 export const Default: StoryObj< typeof ValidatedCheckboxControl > = {
 	render: function Template( { onChange, ...args } ) {
 		const [ checked, setChecked ] = useState( false );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedCheckboxControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedCheckboxControl
@@ -40,6 +47,17 @@ export const Default: StoryObj< typeof ValidatedCheckboxControl > = {
 					setChecked( value );
 					onChange?.( value );
 				} }
+				onValidate={ ( value ) => {
+					if ( value ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'This checkbox may not be checked.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -48,10 +66,4 @@ Default.args = {
 	required: true,
 	label: 'Checkbox',
 	help: 'This checkbox may neither be checked nor unchecked.',
-	customValidator: ( value ) => {
-		if ( value ) {
-			return 'This checkbox may not be checked.';
-		}
-		return undefined;
-	},
 };

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

@@ -15,7 +15,8 @@ import { ValidatedComboboxControl } from '../combobox-control';
 import { formDecorator } from './story-utils';
 
 const meta: Meta< typeof ValidatedComboboxControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedComboboxControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedComboboxControl',
+	id: 'components-validatedcomboboxcontrol',
 	component: ValidatedComboboxControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -34,6 +35,12 @@ export const Default: StoryObj< typeof ValidatedComboboxControl > = {
 					typeof ValidatedComboboxControl
 				>[ 'value' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedComboboxControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedComboboxControl
@@ -43,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 }
 			/>
 		);
 	},
@@ -55,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

@@ -15,7 +15,8 @@ import { ValidatedCustomSelectControl } from '../custom-select-control';
 import { formDecorator } from './story-utils';
 
 const meta: Meta< typeof ValidatedCustomSelectControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedCustomSelectControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedCustomSelectControl',
+	id: 'components-validatedcustomselectcontrol',
 	component: ValidatedCustomSelectControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -34,6 +35,12 @@ export const Default: StoryObj< typeof ValidatedCustomSelectControl > = {
 					typeof ValidatedCustomSelectControl
 				>[ 'value' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedCustomSelectControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedCustomSelectControl
@@ -43,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 }
 			/>
 		);
 	},
@@ -55,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

@@ -22,7 +22,8 @@ import InputControlSuffixWrapper from '../../../input-control/input-suffix-wrapp
 import { Button } from '../../../button';
 
 const meta: Meta< typeof ValidatedInputControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedInputControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedInputControl',
+	id: 'components-validatedinputcontrol',
 	component: ValidatedInputControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -45,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
@@ -54,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 }
 			/>
 		);
 	},
@@ -62,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;
-	},
 };
 
 /**
@@ -82,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
@@ -104,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 }
 			/>
 		);
 	},
@@ -113,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

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

@@ -2,7 +2,7 @@ import { ArgTypes, Meta, Stories } from '@storybook/blocks';
 import * as OverviewStories from './overview.story';
 import { ValidatedInputControl } from '..';
 
-<Meta of={ OverviewStories } title="Components (Private)/Validated Form Controls/Overview" />
+<Meta of={ OverviewStories } title="Components/Selection & Input/Validated Form Controls/Overview" />
 
 # Validated Form Controls
 
@@ -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,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { useState } from '@wordpress/element';
+import { useRef, useCallback, useState } from '@wordpress/element';
 
 /**
  * External dependencies
@@ -14,10 +14,11 @@ 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 (Experimental)/Validated Form Controls/Overview',
-	tags: [ 'status-private' ],
+	title: 'Components/Selection & Input/Validated Form Controls/Overview',
+	id: 'components-validated-form-controls-overview',
 	decorators: formDecorator,
 };
 export default meta;
@@ -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

@@ -15,7 +15,8 @@ import { ValidatedRadioControl } from '../radio-control';
 import { formDecorator } from './story-utils';
 
 const meta: Meta< typeof ValidatedRadioControl > = {
-	title: 'Components (Experimental)/Validated Form Controls/ValidatedRadioControl',
+	title: 'Components/Selection & Input/Validated Form Controls/ValidatedRadioControl',
+	id: 'components-validatedradiocontrol',
 	component: ValidatedRadioControl,
 	tags: [ 'status-private' ],
 	decorators: formDecorator,
@@ -34,6 +35,12 @@ export const Default: StoryObj< typeof ValidatedRadioControl > = {
 					typeof ValidatedRadioControl
 				>[ 'selected' ]
 			>();
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedRadioControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedRadioControl
@@ -43,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 }
 			/>
 		);
 	},
@@ -55,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

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