@wordpress/components 30.9.1-next.8b30e05b0.0 → 31.0.1-next.6deb34194.0

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

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

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

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

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

@@ -35,12 +35,6 @@ export const Default: StoryObj< typeof ValidatedCustomSelectControl > = {
 					typeof ValidatedCustomSelectControl
 				>[ 'value' ]
 			>();
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedCustomSelectControl
-				>[ 'customValidity' ]
-			>( undefined );
 
 		return (
 			<ValidatedCustomSelectControl
@@ -50,17 +44,14 @@ 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 }
+				customValidity={
+					value?.key === 'a'
+						? {
+								type: 'invalid',
+								message: 'Option A is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -36,39 +36,27 @@ export default meta;
 export const Default: StoryObj< typeof ValidatedFormTokenField > = {
 	render: function Template( { onChange, ...args } ) {
 		const [ value, setValue ] = useState< ( string | TokenItem )[] >( [] );
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedFormTokenField
-				>[ 'customValidity' ]
-			>( undefined );
 
 		return (
 			<ValidatedFormTokenField
 				{ ...args }
 				value={ value }
-				onChange={ ( newValue, ...rest ) => {
+				onChange={ ( newValue ) => {
 					setValue( newValue );
-					onChange?.( newValue, ...rest );
+					onChange?.( newValue );
 				} }
-				onValidate={ ( v ) => {
-					if (
-						v?.some( ( token ) => {
-							const tokenValue =
-								typeof token === 'string' ? token : token.value;
-							return tokenValue.toLowerCase() === 'error';
-						} )
-					) {
-						setCustomValidity( {
-							type: 'invalid',
-							message: 'The tag "error" is not allowed.',
-						} );
-						return;
-					}
-
-					setCustomValidity( undefined );
-				} }
-				customValidity={ customValidity }
+				customValidity={
+					value?.some( ( token ) => {
+						const tokenValue =
+							typeof token === 'string' ? token : token.value;
+						return tokenValue.toLowerCase() === 'error';
+					} )
+						? {
+								type: 'invalid',
+								message: 'The tag "error" is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},

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

@@ -42,16 +42,7 @@ export default meta;
 
 export const Default: StoryObj< typeof ValidatedInputControl > = {
 	render: function Template( { onChange, ...args } ) {
-		const [ value, setValue ] =
-			useState<
-				React.ComponentProps< typeof ValidatedInputControl >[ 'value' ]
-			>( '' );
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedInputControl
-				>[ 'customValidity' ]
-			>( undefined );
+		const [ value, setValue ] = useState< string | undefined >( '' );
 
 		return (
 			<ValidatedInputControl
@@ -61,17 +52,14 @@ 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 }
+				customValidity={
+					value?.toLowerCase() === 'error'
+						? {
+								type: 'invalid',
+								message: 'The word "error" is not allowed.',
+						  }
+						: undefined
+				}
 			/>
 		);
 	},
@@ -89,17 +77,8 @@ Default.args = {
  */
 export const Password: StoryObj< typeof ValidatedInputControl > = {
 	render: function Template( { onChange, ...args } ) {
-		const [ value, setValue ] =
-			useState<
-				React.ComponentProps< typeof ValidatedInputControl >[ 'value' ]
-			>( '' );
+		const [ value, setValue ] = useState< string | undefined >( '' );
 		const [ visible, setVisible ] = useState( false );
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedInputControl
-				>[ 'customValidity' ]
-			>( undefined );
 
 		return (
 			<ValidatedInputControl
@@ -122,34 +101,30 @@ export const Password: StoryObj< typeof ValidatedInputControl > = {
 					setValue( newValue );
 					onChange?.( newValue, ...rest );
 				} }
-				onValidate={ ( v ) => {
-					if ( ! /\d/.test( v ?? '' ) ) {
-						setCustomValidity( {
-							type: 'invalid',
+				customValidity={ ( () => {
+					if ( ! /\d/.test( value ?? '' ) ) {
+						return {
+							type: 'invalid' as const,
 							message:
 								'Password must include at least one number.',
-						} );
-						return;
+						};
 					}
-					if ( ! /[A-Z]/.test( v ?? '' ) ) {
-						setCustomValidity( {
-							type: 'invalid',
+					if ( ! /[A-Z]/.test( value ?? '' ) ) {
+						return {
+							type: 'invalid' as const,
 							message:
 								'Password must include at least one capital letter.',
-						} );
-						return;
+						};
 					}
-					if ( ! /[!@£$%^&*#]/.test( v ?? '' ) ) {
-						setCustomValidity( {
-							type: 'invalid',
+					if ( ! /[!@£$%^&*#]/.test( value ?? '' ) ) {
+						return {
+							type: 'invalid' as const,
 							message:
 								'Password must include at least one symbol.',
-						} );
-						return;
+						};
 					}
-					setCustomValidity( undefined );
-				} }
-				customValidity={ customValidity }
+					return undefined;
+				} )() }
 			/>
 		);
 	},

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

@@ -37,32 +37,23 @@ export const Default: StoryObj< typeof ValidatedNumberControl > = {
 			useState<
 				React.ComponentProps< typeof ValidatedNumberControl >[ 'value' ]
 			>();
-		const [ customValidity, setCustomValidity ] =
-			useState<
-				React.ComponentProps<
-					typeof ValidatedNumberControl
-				>[ 'customValidity' ]
-			>( undefined );
 
 		return (
 			<ValidatedNumberControl
 				{ ...args }
 				value={ value }
-				onChange={ ( newValue, ...rest ) => {
+				onChange={ ( newValue, extra ) => {
 					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 );
-					}
+					onChange?.( newValue, extra );
 				} }
-				customValidity={ customValidity }
+				customValidity={
+					value && parseInt( value.toString(), 10 ) % 2 !== 0
+						? {
+								type: 'invalid',
+								message: 'Choose an even number.',
+						  }
+						: 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', 'onValidate', 'customValidity' ] } />
+<ArgTypes of={ ValidatedInputControl } include={ [ 'required', 'markWhenOptional', 'customValidity' ] } />
 
 ## Implementation
 
@@ -32,14 +32,14 @@ These components are designed to work with the native HTML5 [Constraint Validati
 
 ### No easy access to underlying validation APIs
 
-- The consumer does not have a simple way to trigger their custom validators at an arbitrary point in time. Currently, the validation timings for custom validators are handled by the component — first on `blur`, and then on every `change` after the field is considered "touched". Note that this limitation only applies to **custom** validators, not the standard attribute-based validators like `required` or `pattern`, which can be triggered at any time using the `reportValidity()` method on either the underlying control element or the wrapping `<form>` element.
+- The consumer does not have a simple way to show validation messages at an arbitrary point in time, unless the fields are wrapped in a `form` element. Currently, when to show validation messages to the user are handled by the component — any messages are first made visible on `blur` after the field is considered "touched", or if the user tries to submit the enclosing `form`. Messages can also be triggered to show at any time by calling the `reportValidity()` method on the wrapping `<form>` element.
 - The consumer does not have direct access to the [`validity` object](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) of the underlying element.
 
 We don't foresee these being needed much, but it is technically possible by the consumer accessing the target element's validation APIs via `ref`. Better docs or ergonomics can be added when we have actual use cases.
 
 ### Delegate elements
 
-The implementations for `ToggleGroupControl` and `CustomSelectControl` use a "delegate" element for validation, due to upstream limitations that prevent us from using the actual underlying elements for constraint validation. A delegate element in this context is a visually hidden form element that we "delegate" the Constraint Validation API concerns to.
+The implementations for `ToggleGroupControl`, `CustomSelectControl`, and `FormTokenField` use a "delegate" element for validation, due to upstream limitations that prevent us from using the actual underlying elements for constraint validation. A delegate element in this context is a visually hidden form element that we "delegate" the Constraint Validation API concerns to.
 
 This is not ideal, but lets us maintain a consistent mechanism to scroll to the invalid field when attempting to submit, and block the form from submitting. It is hopefully fine as a stopgap, given the low amount of actual validation that will need happen on these two specific components.
 

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
+				}
 			/>
 		);
 	},