Accessibility: Make the Media modal an ARIA modal dialog.

For a number of years, the Media modal missed an explicit ARIA role and the required attributes for modal dialogs.

This was confusing for assistive technology users, since they may not realize they're inside a dialog, and that consequently the keyboard interactions may be different from the rest of the page. Lack of an explicit label for the dialog was confusing as well, since assistive technology users didn't have an immediate sense of what the dialog is for.

This change makes the Media modal meet the ARIA Authoring Practices recommendations, helping users better understand the purpose and interactions with the modal. Also, it makes sure to hide the rest of the page content from assistive technologies, until support for `aria-modal="true"` improves.

Additionally:
- moves the modal H1 heading to the beginning of the modal content 
- changes the modal left menu position to make visual and DOM order match 
- improves the `wp.media.view.FocusManager` documentation

Fixes #47145.

Built from https://develop.svn.wordpress.org/trunk@45572


git-svn-id: http://core.svn.wordpress.org/trunk@45383 1a063a9b-81f0-0310-95a4-ce76da25c4cd

wp-includes/css/media-views-rtl.css

@@ -542,7 +542,7 @@
 	left: 0;
 	bottom: 0;
 	margin: 0;
-	padding: 10px 0;
+	padding: 50px 0 10px;
 	background: #f3f3f3;
 	border-left-width: 1px;
 	border-left-style: solid;
@@ -2530,8 +2530,9 @@
 
 /* Landscape specific header override */
 @media screen and (max-height: 400px) {
-	.media-menu {
-		padding: 0;
+	.media-menu,
+	.media-frame:not(.hide-menu) .media-menu {
+		top: 44px;
 	}
 
 	.media-frame-router {
@@ -2552,6 +2553,14 @@
 	}
 }
 
+@media only screen and (min-width: 901px) and (max-height: 400px) {
+	.media-menu,
+	.media-frame:not(.hide-menu) .media-menu {
+		top: 0;
+		padding-top: 44px;
+	}
+}
+
 @media only screen and (max-width: 480px) {
 	.media-modal-close {
 		top: -5px;
@@ -2578,6 +2587,7 @@
 	.media-frame-router,
 	.media-frame:not(.hide-menu) .media-menu {
 		top: 40px;
+		padding-top: 0;
 	}
 
 	.media-frame-content {

wp-includes/css/media-views.css

@@ -542,7 +542,7 @@
 	right: 0;
 	bottom: 0;
 	margin: 0;
-	padding: 10px 0;
+	padding: 50px 0 10px;
 	background: #f3f3f3;
 	border-right-width: 1px;
 	border-right-style: solid;
@@ -2530,8 +2530,9 @@
 
 /* Landscape specific header override */
 @media screen and (max-height: 400px) {
-	.media-menu {
-		padding: 0;
+	.media-menu,
+	.media-frame:not(.hide-menu) .media-menu {
+		top: 44px;
 	}
 
 	.media-frame-router {
@@ -2552,6 +2553,14 @@
 	}
 }
 
+@media only screen and (min-width: 901px) and (max-height: 400px) {
+	.media-menu,
+	.media-frame:not(.hide-menu) .media-menu {
+		top: 0;
+		padding-top: 44px;
+	}
+}
+
 @media only screen and (max-width: 480px) {
 	.media-modal-close {
 		top: -5px;
@@ -2578,6 +2587,7 @@
 	.media-frame-router,
 	.media-frame:not(.hide-menu) .media-menu {
 		top: 40px;
+		padding-top: 0;
 	}
 
 	.media-frame-content {

wp-includes/js/media-views.js

@@ -4418,6 +4418,9 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
 		// Set initial focus on the content instead of this view element, to avoid page scrolling.
 		this.$( '.media-modal' ).focus();
 
+		// Hide the page content from assistive technologies.
+		this.focusManager.setAriaHiddenOnBodyChildren( $el );
+
 		return this.propagate('open');
 	},
 
@@ -4436,6 +4439,12 @@ Modal = wp.media.View.extend(/** @lends wp.media.view.Modal.prototype */{
 		// Hide modal and remove restricted media modal tab focus once it's closed
 		this.$el.hide().undelegate( 'keydown' );
 
+		/*
+		 * Make visible again to assistive technologies all body children that
+		 * have been made hidden when the modal opened.
+		 */
+		this.focusManager.removeAriaHiddenFromBodyChildren();
+
 		// Move focus back in useful location once modal is closed.
 		if ( null !== this.clickedOpenerEl ) {
 			// Move focus back to the element that opened the modal.
@@ -4531,6 +4540,10 @@ var FocusManager = wp.media.View.extend(/** @lends wp.media.view.FocusManager.pr
 
 	/**
 	 * Gets all the tabbable elements.
+	 *
+	 * @since 5.3.0
+	 *
+	 * @returns {object} A jQuery collection of tabbable elements.
 	 */
 	getTabbables: function() {
 		// Skip the file input added by Plupload.
@@ -4539,13 +4552,23 @@ var FocusManager = wp.media.View.extend(/** @lends wp.media.view.FocusManager.pr
 
 	/**
 	 * Moves focus to the modal dialog.
+	 *
+	 * @since 3.5.0
+	 *
+	 * @returns {void}
 	 */
 	focus: function() {
 		this.$( '.media-modal' ).focus();
 	},
 
 	/**
-	 * @param {Object} event
+	 * Constrains navigation with the Tab key within the media view element.
+	 *
+	 * @since 4.0.0
+	 *
+	 * @param {Object} event A keydown jQuery event.
+	 *
+	 * @returns {void}
 	 */
 	constrainTabbing: function( event ) {
 		var tabbables;
@@ -4565,8 +4588,107 @@ var FocusManager = wp.media.View.extend(/** @lends wp.media.view.FocusManager.pr
 			tabbables.last().focus();
 			return false;
 		}
-	}
+	},
 
+	/**
+	 * Hides from assistive technologies all the body children except the
+	 * provided element and other elements that should not be hidden.
+	 *
+	 * The reason why we use `aria-hidden` is that `aria-modal="true"` is buggy
+	 * in Safari 11.1 and support is spotty in other browsers. In the future we
+	 * should consider to remove this helper function and only use `aria-modal="true"`.
+	 *
+	 * @since 5.3.0
+	 *
+	 * @param {object} visibleElement The jQuery object representing the element that should not be hidden.
+	 *
+	 * @returns {void}
+	 */
+	setAriaHiddenOnBodyChildren: function( visibleElement ) {
+		var bodyChildren,
+			self = this;
+
+		if ( this.isBodyAriaHidden ) {
+			return;
+		}
+
+		// Get all the body children.
+		bodyChildren = document.body.children;
+
+		// Loop through the body children and hide the ones that should be hidden.
+		_.each( bodyChildren, function( element ) {
+			// Don't hide the modal element.
+			if ( element === visibleElement[0] ) {
+				return;
+			}
+
+			// Determine the body children to hide.
+			if ( self.elementShouldBeHidden( element ) ) {
+				element.setAttribute( 'aria-hidden', 'true' );
+				// Store the hidden elements.
+				self.ariaHiddenElements.push( element );
+			}
+		} );
+
+		this.isBodyAriaHidden = true;
+	},
+
+	/**
+	 * Makes visible again to assistive technologies all body children
+	 * previously hidden and stored in this.ariaHiddenElements.
+	 *
+	 * @since 5.3.0
+	 *
+	 * @returns {void}
+	 */
+	removeAriaHiddenFromBodyChildren: function() {
+		_.each( this.ariaHiddenElements, function( element ) {
+			element.removeAttribute( 'aria-hidden' );
+		} );
+
+		this.ariaHiddenElements = [];
+		this.isBodyAriaHidden   = false;
+	},
+
+	/**
+	 * Determines if the passed element should not be hidden from assistive technologies.
+	 *
+	 * @since 5.3.0
+	 *
+	 * @param {object} element The DOM element that should be checked.
+	 *
+	 * @returns {boolean} Whether the element should not be hidden from assistive technologies.
+	 */
+	elementShouldBeHidden: function( element ) {
+		var role = element.getAttribute( 'role' ),
+			liveRegionsRoles = [ 'alert', 'status', 'log', 'marquee', 'timer' ];
+
+		/*
+		 * Don't hide scripts, elements that already have `aria-hidden`, and
+		 * ARIA live regions.
+		 */
+		return ! (
+			element.tagName === 'SCRIPT' ||
+			element.hasAttribute( 'aria-hidden' ) ||
+			element.hasAttribute( 'aria-live' ) ||
+			liveRegionsRoles.indexOf( role ) !== -1
+		);
+	},
+
+	/**
+	 * Whether the body children are hidden from assistive technologies.
+	 *
+	 * @since 5.3.0
+	 */
+	isBodyAriaHidden: false,
+
+	/**
+	 * Stores an array of DOM elements that should be hidden from assistive
+	 * technologies, for example when the media modal dialog opens.
+	 *
+	 * @since 5.3.0
+	 */
+	ariaHiddenElements: []
 });
 
 module.exports = FocusManager;

wp-includes/media-template.php

@@ -177,8 +177,8 @@ function wp_print_media_templates() {
 
 	<?php // Template for the media frame: used both in the media grid and in the media modal. ?>
 	<script type="text/html" id="tmpl-media-frame">
+		<div class="media-frame-title" id="media-frame-title"></div>
 		<div class="media-frame-menu"></div>
-		<div class="media-frame-title"></div>
 		<div class="media-frame-router"></div>
 		<div class="media-frame-content"></div>
 		<div class="media-frame-toolbar"></div>
@@ -187,11 +187,11 @@ function wp_print_media_templates() {
 
 	<?php // Template for the media modal. ?>
 	<script type="text/html" id="tmpl-media-modal">
-		<div tabindex="0" class="<?php echo $class; ?>">
+		<div tabindex="0" class="<?php echo $class; ?>" role="dialog" aria-modal="true" aria-labelledby="media-frame-title">
 			<# if ( data.hasCloseButton ) { #>
 				<button type="button" class="media-modal-close"><span class="media-modal-icon"><span class="screen-reader-text"><?php _e( 'Close dialog' ); ?></span></span></button>
 			<# } #>
-			<div class="media-modal-content"></div>
+			<div class="media-modal-content" role="document"></div>
 		</div>
 		<div class="media-modal-backdrop"></div>
 	</script>

wp-includes/version.php

@@ -13,7 +13,7 @@
  *
  * @global string $wp_version
  */
-$wp_version = '5.3-alpha-45571';
+$wp_version = '5.3-alpha-45572';
 
 /**
  * Holds the WordPress DB revision, increments when changes are made to the WordPress DB schema.