From de3fbdecc0eca1ec876dfd04bbf642a7f60a57b4 Mon Sep 17 00:00:00 2001
From: Joe Dolson <joedolson@git.wordpress.org>
Date: Fri, 19 Aug 2022 23:04:04 +0000
Subject: [PATCH] Taxonomy: Associate field descriptions with fields.

Use `aria-describedby` to associate the field descriptions and instructions with the form fields when creating or editing taxonomy terms.

Props afercia.
Fixes #55651.

git-svn-id: https://develop.svn.wordpress.org/trunk@53913 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/edit-tag-form.php        | 17 +++++++++--------
 src/wp-admin/edit-tags.php            | 18 ++++++++++--------
 src/wp-includes/category-template.php |  8 +++++++-
 3 files changed, 26 insertions(+), 17 deletions(-)

diff --git a/src/wp-admin/edit-tag-form.php b/src/wp-admin/edit-tag-form.php
index 7c22cf471d..9b2110398c 100644
--- a/src/wp-admin/edit-tag-form.php
+++ b/src/wp-admin/edit-tag-form.php
@@ -145,8 +145,8 @@ if ( isset( $tag->name ) ) {
 	<table class="form-table" role="presentation">
 		<tr class="form-field form-required term-name-wrap">
 			<th scope="row"><label for="name"><?php _ex( 'Name', 'term name' ); ?></label></th>
-			<td><input name="name" id="name" type="text" value="<?php echo $tag_name_value; ?>" size="40" aria-required="true" />
-			<p class="description"><?php echo $tax->labels->name_field_description; ?></p></td>
+			<td><input name="name" id="name" type="text" value="<?php echo $tag_name_value; ?>" size="40" aria-required="true" aria-describedby="name-description" />
+			<p class="description" id="name-description"><?php echo $tax->labels->name_field_description; ?></p></td>
 		</tr>
 <?php if ( ! global_terms_enabled() ) { ?>
 		<tr class="form-field term-slug-wrap">
@@ -167,8 +167,8 @@ if ( isset( $tag->name ) ) {
 			 */
 			$slug = isset( $tag->slug ) ? apply_filters( 'editable_slug', $tag->slug, $tag ) : '';
 			?>
-			<td><input name="slug" id="slug" type="text" value="<?php echo esc_attr( $slug ); ?>" size="40" />
-			<p class="description"><?php echo $tax->labels->slug_field_description; ?></p></td>
+			<td><input name="slug" id="slug" type="text" value="<?php echo esc_attr( $slug ); ?>" size="40" aria-describedby="slug-description" />
+			<p class="description" id="slug-description"><?php echo $tax->labels->slug_field_description; ?></p></td>
 		</tr>
 <?php } ?>
 <?php if ( is_taxonomy_hierarchical( $taxonomy ) ) : ?>
@@ -186,6 +186,7 @@ if ( isset( $tag->name ) ) {
 					'exclude_tree'     => $tag->term_id,
 					'hierarchical'     => true,
 					'show_option_none' => __( 'None' ),
+					'aria_describedby' => 'parent-description',
 				);
 
 				/** This filter is documented in wp-admin/edit-tags.php */
@@ -193,17 +194,17 @@ if ( isset( $tag->name ) ) {
 				wp_dropdown_categories( $dropdown_args );
 				?>
 				<?php if ( 'category' === $taxonomy ) : ?>
-					<p class="description"><?php _e( 'Categories, unlike tags, can have a hierarchy. You might have a Jazz category, and under that have children categories for Bebop and Big Band. Totally optional.' ); ?></p>
+					<p class="description" id="parent-description"><?php _e( 'Categories, unlike tags, can have a hierarchy. You might have a Jazz category, and under that have children categories for Bebop and Big Band. Totally optional.' ); ?></p>
 				<?php else : ?>
-					<p class="description"><?php echo $tax->labels->parent_field_description; ?></p>
+					<p class="description" id="parent-description"><?php echo $tax->labels->parent_field_description; ?></p>
 				<?php endif; ?>
 			</td>
 		</tr>
 <?php endif; // is_taxonomy_hierarchical() ?>
 		<tr class="form-field term-description-wrap">
 			<th scope="row"><label for="description"><?php _e( 'Description' ); ?></label></th>
-			<td><textarea name="description" id="description" rows="5" cols="50" class="large-text"><?php echo $tag->description; // textarea_escaped ?></textarea>
-			<p class="description"><?php echo $tax->labels->desc_field_description; ?></p></td>
+			<td><textarea name="description" id="description" rows="5" cols="50" class="large-text" aria-describedby="description-description"><?php echo $tag->description; // textarea_escaped ?></textarea>
+			<p class="description" id="description-description"><?php echo $tax->labels->desc_field_description; ?></p></td>
 		</tr>
 		<?php
 		// Back compat hooks.
diff --git a/src/wp-admin/edit-tags.php b/src/wp-admin/edit-tags.php
index cab8ff48de..abbc330b82 100644
--- a/src/wp-admin/edit-tags.php
+++ b/src/wp-admin/edit-tags.php
@@ -453,14 +453,14 @@ if ( $can_edit_terms ) {
 
 <div class="form-field form-required term-name-wrap">
 	<label for="tag-name"><?php _ex( 'Name', 'term name' ); ?></label>
-	<input name="tag-name" id="tag-name" type="text" value="" size="40" aria-required="true" />
-	<p><?php echo $tax->labels->name_field_description; ?></p>
+	<input name="tag-name" id="tag-name" type="text" value="" size="40" aria-required="true" aria-describedby="name-description" />
+	<p id="name-description"><?php echo $tax->labels->name_field_description; ?></p>
 </div>
 	<?php if ( ! global_terms_enabled() ) : ?>
 <div class="form-field term-slug-wrap">
 	<label for="tag-slug"><?php _e( 'Slug' ); ?></label>
-	<input name="slug" id="tag-slug" type="text" value="" size="40" />
-	<p><?php echo $tax->labels->slug_field_description; ?></p>
+	<input name="slug" id="tag-slug" type="text" value="" size="40" aria-describedby="slug-description" />
+	<p id="slug-description"><?php echo $tax->labels->slug_field_description; ?></p>
 </div>
 <?php endif; // global_terms_enabled() ?>
 	<?php if ( is_taxonomy_hierarchical( $taxonomy ) ) : ?>
@@ -500,19 +500,21 @@ if ( $can_edit_terms ) {
 		 */
 		$dropdown_args = apply_filters( 'taxonomy_parent_dropdown_args', $dropdown_args, $taxonomy, 'new' );
 
+		$dropdown_args['aria_describedby'] = 'parent-description';
+
 		wp_dropdown_categories( $dropdown_args );
 		?>
 		<?php if ( 'category' === $taxonomy ) : ?>
-		<p><?php _e( 'Categories, unlike tags, can have a hierarchy. You might have a Jazz category, and under that have children categories for Bebop and Big Band. Totally optional.' ); ?></p>
+		<p id="parent-description"><?php _e( 'Categories, unlike tags, can have a hierarchy. You might have a Jazz category, and under that have children categories for Bebop and Big Band. Totally optional.' ); ?></p>
 	<?php else : ?>
-		<p><?php echo $tax->labels->parent_field_description; ?></p>
+		<p id="parent-description"><?php echo $tax->labels->parent_field_description; ?></p>
 	<?php endif; ?>
 </div>
 	<?php endif; // is_taxonomy_hierarchical() ?>
 <div class="form-field term-description-wrap">
 	<label for="tag-description"><?php _e( 'Description' ); ?></label>
-	<textarea name="description" id="tag-description" rows="5" cols="40"></textarea>
-	<p><?php echo $tax->labels->desc_field_description; ?></p>
+	<textarea name="description" id="tag-description" rows="5" cols="40" aria-describedby="description-description"></textarea>
+	<p id="description-description"><?php echo $tax->labels->desc_field_description; ?></p>
 </div>
 
 	<?php
diff --git a/src/wp-includes/category-template.php b/src/wp-includes/category-template.php
index c9e91a6f41..dc0dfe7ef0 100644
--- a/src/wp-includes/category-template.php
+++ b/src/wp-includes/category-template.php
@@ -300,6 +300,7 @@ function category_description( $category = 0 ) {
  * @since 2.1.0
  * @since 4.2.0 Introduced the `value_field` argument.
  * @since 4.6.0 Introduced the `required` argument.
+ * @since 6.1.0 Introduced the `aria_describedby` argument.
  *
  * @param array|string $args {
  *     Optional. Array or string of arguments to generate a categories drop-down element. See WP_Term_Query::__construct()
@@ -335,6 +336,8 @@ function category_description( $category = 0 ) {
  *                                           Default false.
  *     @type Walker       $walker            Walker object to use to build the output. Default empty which results in a
  *                                           Walker_CategoryDropdown instance being used.
+ *     @type string       $aria_describedby  The 'id' of an element that contains descriptive text for the select.
+ *                                           Default empty string.
  * }
  * @return string HTML dropdown list of categories.
  */
@@ -361,6 +364,7 @@ function wp_dropdown_categories( $args = '' ) {
 		'option_none_value' => -1,
 		'value_field'       => 'term_id',
 		'required'          => false,
+		'aria_describedby'  => '',
 	);
 
 	$defaults['selected'] = ( is_category() ) ? get_query_var( 'cat' ) : 0;
@@ -406,8 +410,10 @@ function wp_dropdown_categories( $args = '' ) {
 	$id       = $parsed_args['id'] ? esc_attr( $parsed_args['id'] ) : $name;
 	$required = $parsed_args['required'] ? 'required' : '';
 
+	$aria_describedby_attribute = $parsed_args['aria_describedby'] ? ' aria-describedby="' . esc_attr( $parsed_args['aria_describedby'] ) . '"' : '';
+
 	if ( ! $parsed_args['hide_if_empty'] || ! empty( $categories ) ) {
-		$output = "<select $required name='$name' id='$id' class='$class' $tab_index_attribute>\n";
+		$output = "<select $required name='$name' id='$id' class='$class'$tab_index_attribute$aria_describedby_attribute>\n";
 	} else {
 		$output = '';
 	}