@wordpress/components 30.9.0 → 31.0.0

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

@@ -10,48 +10,33 @@ import { useMergeRefs } from '@wordpress/compose';
 import { ControlWithError } from '../control-with-error';
 import NumberControl from '../../number-control';
 import type { ValidatedControlProps } from './types';
-import type { NumberControlProps } from '../../number-control/types';
-
-type Value = NumberControlProps[ 'value' ];
 
 const UnforwardedValidatedNumberControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof NumberControl >,
 		'__next40pxDefaultSize'
 	> &
-		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 }
 		>
 			<NumberControl
 				__next40pxDefaultSize
 				ref={ mergedRefs }
-				// TODO: Upstream limitation - When form is submitted when value is undefined, it will
-				// automatically set a clamped value (as defined by `min` attribute, so 0 by default).
-				onChange={ ( value, ...args ) => {
-					valueRef.current = value;
-					onChange?.( value, ...args );
-				} }
 				{ ...restProps }
 			/>
 		</ControlWithError>

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

@@ -10,25 +10,18 @@ import { forwardRef, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import RadioControl from '../../radio-control';
-import type { RadioControlProps } from '../../radio-control/types';
-
-type Value = RadioControlProps[ 'selected' ];
 
 const UnforwardedValidatedRadioControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
-	}: React.ComponentProps< typeof RadioControl > &
-		ValidatedControlProps< Value >,
+	}: React.ComponentProps< typeof RadioControl > & ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLDivElement >
 ) => {
 	const validityTargetRef = useRef< HTMLDivElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
-	const valueRef = useRef< Value >( restProps.selected );
 
 	return (
 		<ControlWithError
@@ -36,9 +29,6 @@ const UnforwardedValidatedRadioControl = (
 			markWhenOptional={ markWhenOptional }
 			// TODO: Upstream limitation - RadioControl does not accept a ref.
 			ref={ mergedRefs }
-			onValidate={ () => {
-				return onValidate?.( valueRef.current );
-			} }
 			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
@@ -46,13 +36,7 @@ const UnforwardedValidatedRadioControl = (
 				)
 			}
 		>
-			<RadioControl
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
-				{ ...restProps }
-			/>
+			<RadioControl { ...restProps } />
 		</ControlWithError>
 	);
 };

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

@@ -10,36 +10,27 @@ import { forwardRef, useRef } from '@wordpress/element';
 import { ControlWithError } from '../control-with-error';
 import type { ValidatedControlProps } from './types';
 import RangeControl from '../../range-control';
-import type { RangeControlProps } from '../../range-control/types';
-
-type Value = RangeControlProps[ 'value' ];
 
 const UnforwardedValidatedRangeControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
 		React.ComponentProps< typeof RangeControl >,
 		'__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 UnforwardedValidatedRangeControl = (
 				__next40pxDefaultSize
 				__nextHasNoMarginBottom
 				ref={ mergedRefs }
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
 				{ ...restProps }
 			/>
 		</ControlWithError>

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

@@ -10,25 +10,11 @@ import { useMergeRefs } from '@wordpress/compose';
 import { ControlWithError } from '../control-with-error';
 import SelectControl from '../../select-control';
 import type { ValidatedControlProps } from './types';
-import type { SelectControlProps as _SelectControlProps } from '../../select-control/types';
-
-// Only support single value selection
-type SelectControlProps = Omit<
-	_SelectControlProps,
-	'multiple' | 'onChange' | 'value'
-> & {
-	onChange?: ( value: string ) => void;
-	value?: string;
-};
-
-type Value = SelectControlProps[ 'value' ];
 
 const UnforwardedValidatedSelectControl = (
 	{
 		required,
-		onValidate,
 		customValidity,
-		onChange,
 		markWhenOptional,
 		...restProps
 	}: Omit<
@@ -41,20 +27,16 @@ const UnforwardedValidatedSelectControl = (
 	> & {
 		value?: string;
 		onChange: ( value: string ) => void;
-	} & ValidatedControlProps< Value >,
+	} & ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLSelectElement >
 ) => {
 	const validityTargetRef = useRef< HTMLSelectElement >( 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 }
 		>
@@ -62,10 +44,6 @@ const UnforwardedValidatedSelectControl = (
 				__nextHasNoMarginBottom
 				__next40pxDefaultSize
 				ref={ mergedRefs }
-				onChange={ ( value ) => {
-					valueRef.current = value;
-					onChange?.( value );
-				} }
 				{ ...restProps }
 			/>
 		</ControlWithError>

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.