From af0242a37b972dfc0eee1e1424268dd866edc181 Mon Sep 17 00:00:00 2001
From: Andrea Fercia <afercia@git.wordpress.org>
Date: Wed, 10 Apr 2019 19:59:16 +0000
Subject: [PATCH] Accessibility: Improve the image "Alternative Text" field in
 the Edit Media screen.

Brings parity with the changes for the Media Views introduced in [44900].
- moves the alt text field to the top as first field
- adds an explanatory text with a link pointing to the W3C "alt decision tree" tutorial
- adds `aria-describedby` to target the explanatory text
- adjusts the CSS and indentation

Props chetan200891.
Fixes #46875.


git-svn-id: https://develop.svn.wordpress.org/trunk@45158 602fd350-edb4-49c9-b593-d223f7449a82
---
 src/wp-admin/css/media.css      |  7 ++++++
 src/wp-admin/includes/media.php | 40 ++++++++++++++++++++++-----------
 2 files changed, 34 insertions(+), 13 deletions(-)

diff --git a/src/wp-admin/css/media.css b/src/wp-admin/css/media.css
index c45fa3b331..bb0f952aec 100644
--- a/src/wp-admin/css/media.css
+++ b/src/wp-admin/css/media.css
@@ -825,6 +825,13 @@ border color while dragging a file over the uploader drop area */
 /*------------------------------------------------------------------------------
   14.2 - Image Editor
 ------------------------------------------------------------------------------*/
+.wp_attachment_details .attachment-alt-text {
+	margin-bottom: 5px;
+}
+
+.wp_attachment_details .attachment-alt-text-description {
+	margin-top: 5px;
+}
 
 .wp_attachment_details label[for="content"] {
 	font-size: 13px;
diff --git a/src/wp-admin/includes/media.php b/src/wp-admin/includes/media.php
index b07f4e5bc8..e30cc08b1b 100644
--- a/src/wp-admin/includes/media.php
+++ b/src/wp-admin/includes/media.php
@@ -3012,19 +3012,33 @@ function edit_form_image_editor( $post ) {
 	?>
 	</div>
 	<div class="wp_attachment_details edit-form-section">
+	<?php if ( 'image' === substr( $post->post_mime_type, 0, 5 ) ) : ?>
+		<p class="attachment-alt-text">
+			<label for="attachment_alt"><strong><?php _e( 'Alternative Text' ); ?></strong></label><br />
+			<input type="text" class="widefat" name="_wp_attachment_image_alt" id="attachment_alt" aria-describedby="alt-text-description" value="<?php echo esc_attr( $alt_text ); ?>" />
+		</p>
+		<p class="attachment-alt-text-description" id="alt-text-description">
+			<?php
+			printf(
+				/* translators: 1: link start tag, 2: accessibility text, 3: link end tag */
+				__( '%1$sDescribe the purpose of the image%2$s%3$s. Leave empty if the image is purely decorative.' ),
+				'<a href="' . esc_url( 'https://www.w3.org/WAI/tutorials/images/decision-tree' ) . '" target="_blank" rel="noopener noreferrer">',
+				sprintf(
+					'<span class="screen-reader-text"> %s</span>',
+					/* translators: accessibility text */
+					__( '(opens in a new tab)' )
+				),
+				'</a>'
+			);
+			?>
+		</p>
+	<?php endif; ?>
+
 		<p>
 			<label for="attachment_caption"><strong><?php _e( 'Caption' ); ?></strong></label><br />
 			<textarea class="widefat" name="excerpt" id="attachment_caption"><?php echo $post->post_excerpt; ?></textarea>
 		</p>
 
-
-	<?php if ( 'image' === substr( $post->post_mime_type, 0, 5 ) ) : ?>
-		<p>
-			<label for="attachment_alt"><strong><?php _e( 'Alternative Text' ); ?></strong></label><br />
-			<input type="text" class="widefat" name="_wp_attachment_image_alt" id="attachment_alt" value="<?php echo esc_attr( $alt_text ); ?>" />
-		</p>
-	<?php endif; ?>
-
 	<?php
 		$quicktags_settings = array( 'buttons' => 'strong,em,link,block,del,ins,img,ul,ol,li,code,close' );
 		$editor_args        = array(
@@ -3037,11 +3051,11 @@ function edit_form_image_editor( $post ) {
 	?>
 
 	<label for="attachment_content"><strong><?php _e( 'Description' ); ?></strong>
-														<?php
-														if ( preg_match( '#^(audio|video)/#', $post->post_mime_type ) ) {
-															echo ': ' . __( 'Displayed on attachment pages.' );
-														}
-														?>
+		<?php
+		if ( preg_match( '#^(audio|video)/#', $post->post_mime_type ) ) {
+			echo ': ' . __( 'Displayed on attachment pages.' );
+		}
+		?>
 	</label>
 	<?php wp_editor( $post->post_content, 'attachment_content', $editor_args ); ?>