Accessibility: Improve the sidebar toggles in the Widgets screen.

- uses button elements for the toggles
- uses `aria-expanded` on the toggles to communicate to assistive technologies the panels expanded/collapsed state
- adds the "circular focus" style to the toggles to give users a clear indication of the currently focused element
- standardizes CSS class names to `.toggle-indicator` and `.handlediv` as these names are already used across the admin for similar controls

Props monikarao, xavortm, mihai2u, Kopepasah.
Fixes #37013.


git-svn-id: https://develop.svn.wordpress.org/trunk@41621 602fd350-edb4-49c9-b593-d223f7449a82

src/wp-admin/css/common.css

@@ -2966,7 +2966,7 @@ img {
 }
 
 /* Metabox collapse arrow indicators */
-.js .sidebar-name .sidebar-name-arrow:before,
+.sidebar-name .toggle-indicator:before,
 .js .meta-box-sortables .postbox .toggle-indicator:before,
 .bulk-action-notice .toggle-indicator:before {
 	content: "\f142";
@@ -2978,26 +2978,12 @@ img {
 	text-decoration: none !important;
 }
 
-.js .widgets-holder-wrap.closed .sidebar-name-arrow:before,
+.js .widgets-holder-wrap.closed .toggle-indicator:before,
 .js .meta-box-sortables .postbox.closed .handlediv .toggle-indicator:before,
 .bulk-action-notice .bulk-action-errors-collapsed .toggle-indicator:before {
 	content: "\f140";
 }
 
-.js .sidebar-name .sidebar-name-arrow:before {
-	padding: 10px;
-	left: 0;
-}
-
-.js #widgets-left .sidebar-name .sidebar-name-arrow {
-	display: none;
-}
-
-.js #widgets-left .widgets-holder-wrap.closed .sidebar-name .sidebar-name-arrow,
-.js #widgets-left .sidebar-name:hover .sidebar-name-arrow {
-	display: block;
-}
-
 .js .postbox .handlediv .toggle-indicator:before {
 	margin-top: 4px;
 	width: 20px;
@@ -3171,7 +3157,7 @@ img {
 .handlediv,
 .postbox .handlediv.button-link,
 .item-edit,
-.sidebar-name-arrow,
+.toggle-indicator,
 .accordion-section-title:after {
 	color: #72777c;
 }
@@ -3188,7 +3174,7 @@ img {
 .postbox .handlediv.button-link:focus,
 .item-edit:hover,
 .item-edit:focus,
-.sidebar-name:hover .sidebar-name-arrow,
+.sidebar-name:hover .toggle-indicator,
 .accordion-section-title:hover:after {
 	color: #23282d;
 }
@@ -3488,8 +3474,8 @@ img {
 	#screen-meta-links a.show-settings,
 	.widget-top .widget-action,
 	.widget-top .widget-action:hover,
-	.sidebar-name-arrow,
+	.sidebar-name .toggle-indicator,
-	.sidebar-name:hover .sidebar-name-arrow,
+	.sidebar-name:hover .toggle-indicator,
 	.meta-box-sortables .postbox:hover .handlediv,
 	#bulk-titles div a,
 	#bulk-titles div a:hover {

src/wp-admin/css/widgets.css

@@ -260,17 +260,52 @@
 	box-sizing: border-box;
 }
 
-.sidebar-name-arrow {
-	position: absolute;
-	top: 0;
-	right: 0;
-	bottom: 0;
-}
-
 .js .sidebar-name {
 	cursor: pointer;
 }
 
+.sidebar-name .handlediv {
+	float: right;
+	width: 38px;
+	height: 38px;
+	border: 0;
+	margin: 0;
+	padding: 8px;
+	background: none;
+	cursor: pointer;
+	outline: none;
+}
+
+#widgets-right .sidebar-name .handlediv {
+	margin: 5px 3px 0 0;
+}
+
+.sidebar-name .handlediv:focus {
+	box-shadow: none;
+	outline: none;
+}
+
+#widgets-left .sidebar-name .toggle-indicator {
+	display: none;
+}
+
+#widgets-left .widgets-holder-wrap.closed .sidebar-name .toggle-indicator,
+#widgets-left .sidebar-name:hover .toggle-indicator,
+#widgets-left .sidebar-name .handlediv:focus .toggle-indicator {
+	display: block;
+}
+
+.sidebar-name .toggle-indicator:before {
+	padding: 1px 2px 1px 0;
+	border-radius: 50%;
+}
+
+.sidebar-name .handlediv:focus .toggle-indicator:before {
+	box-shadow:
+		0 0 0 1px #5b9dd9,
+		0 0 2px 1px rgba(30, 140, 190, .8);
+}
+
 .sidebar-name h2,
 .sidebar-name h3 {
 	margin: 0;
@@ -325,10 +360,6 @@ div#widgets-left .sidebar-name h3 {
 	margin: 0 10px 0 0;
 }
 
-#widgets-left .sidebar-name .sidebar-name-arrow:before {
-	padding: 9px;
-}
-
 #widgets-left .widgets-holder-wrap,
 div#widgets-left .widget-holder {
 	background: transparent;
@@ -423,10 +454,6 @@ div#widgets-right .sidebar-name h3 {
 	padding: 15px 7px;
 }
 
-div#widgets-right .sidebar-name .sidebar-name-arrow:before {
-	top: 2px;
-}
-
 div#widgets-right .widget-top {
 	padding: 0;
 }
@@ -556,7 +583,7 @@ div#widgets-right .closed .widgets-sortables {
 .widget-control-noform,
 #access-off,
 .widgets_access .widget-action,
-.widgets_access .sidebar-name-arrow,
+.widgets_access .handlediv,
 .widgets_access #access-on,
 .widgets_access .widget-holder .description,
 .no-js .widget-holder .description {

src/wp-admin/includes/widgets.php

@@ -80,7 +80,10 @@ function wp_list_widget_controls( $sidebar, $sidebar_name = '' ) {
 	if ( $sidebar_name ) {
 		?>
 		<div class="sidebar-name">
-			<div class="sidebar-name-arrow"><br /></div>
+			<button type="button" class="handlediv hide-if-no-js" aria-expanded="true">
+				<span class="screen-reader-text"><?php echo esc_html( $sidebar_name ); ?></span>
+				<span class="toggle-indicator" aria-hidden="true"></span>
+			</button>
 			<h2><?php echo esc_html( $sidebar_name ); ?> <span class="spinner"></span></h2>
 		</div>
 		<?php

src/wp-admin/js/widgets.js

@@ -39,19 +39,42 @@ wpWidgets = {
 			sidebars = $('div.widgets-sortables'),
 			isRTL = !! ( 'undefined' !== typeof isRtl && isRtl );
 
-		$('#widgets-right .sidebar-name').click( function() {
+		// Handle the widgets containers in the right column.
-			var $this = $(this),
+		$( '#widgets-right .sidebar-name' )
-				$wrap = $this.closest('.widgets-holder-wrap');
+			/*
+			 * Toggle the widgets containers when clicked and update the toggle
+			 * button `aria-expanded` attribute value.
+			 */
+			.click( function() {
+				var $this = $( this ),
+					$wrap = $this.closest( '.widgets-holder-wrap '),
+					$toggle = $this.find( '.handlediv' );
 
-			if ( $wrap.hasClass('closed') ) {
+				if ( $wrap.hasClass( 'closed' ) ) {
-				$wrap.removeClass('closed');
+					$wrap.removeClass( 'closed' );
-				$this.parent().sortable('refresh');
+					$toggle.attr( 'aria-expanded', 'true' );
-			} else {
+					// Refresh the jQuery UI sortable items.
-				$wrap.addClass('closed');
+					$this.parent().sortable( 'refresh' );
-			}
+				} else {
+					$wrap.addClass( 'closed' );
+					$toggle.attr( 'aria-expanded', 'false' );
+				}
 
-			$document.triggerHandler( 'wp-pin-menu' );
+				// Update the admin menu "sticky" state.
-		});
+				$document.triggerHandler( 'wp-pin-menu' );
+			})
+			/*
+			 * Set the initial `aria-expanded` attribute value on the widgets
+			 * containers toggle button. The first one is expanded by default.
+			 */
+			.find( '.handlediv' ).each( function( index ) {
+				if ( 0 === index ) {
+					// jQuery equivalent of `continue` within an `each()` loop.
+					return;
+				}
+
+				$( this ).attr( 'aria-expanded', 'false' );
+			});
 
 		// Show AYS dialog when there are unsaved widget changes.
 		$( window ).on( 'beforeunload.widgets', function( event ) {
@@ -86,8 +109,15 @@ wpWidgets = {
 			}
 		});
 
-		$('#widgets-left .sidebar-name').click( function() {
+		// Handle the widgets containers in the left column.
-			$(this).closest('.widgets-holder-wrap').toggleClass('closed');
+		$( '#widgets-left .sidebar-name' ).click( function() {
+			var $wrap = $( this ).closest( '.widgets-holder-wrap' );
+
+			$wrap
+				.toggleClass( 'closed' )
+				.find( '.handlediv' ).attr( 'aria-expanded', ! $wrap.hasClass( 'closed' ) );
+
+			// Update the admin menu "sticky" state.
 			$document.triggerHandler( 'wp-pin-menu' );
 		});
 
@@ -215,7 +245,7 @@ wpWidgets = {
 			/**
 			 * Open Sidebar when a Widget gets dragged over it.
 			 *
-			 * @param event
+			 * @param {object} event jQuery event object.
 			 */
 			over: function( event ) {
 				var $wrap = $( event.target ).parent();
@@ -227,7 +257,9 @@ wpWidgets = {
 
 				if ( $wrap.hasClass( 'closed' ) ) {
 					wpWidgets.hoveredSidebar = $wrap;
-					$wrap.removeClass( 'closed' );
+					$wrap
+						.removeClass( 'closed' )
+						.find( '.handlediv' ).attr( 'aria-expanded', 'true' );
 				}
 
 				$( this ).sortable( 'refresh' );
@@ -236,7 +268,7 @@ wpWidgets = {
 			/**
 			 * Close Sidebar when the Widget gets dragged out of it.
 			 *
-			 * @param event
+			 * @param {object} event jQuery event object.
 			 */
 			out: function( event ) {
 				if ( wpWidgets.hoveredSidebar ) {
@@ -319,7 +351,10 @@ wpWidgets = {
 				$sidebar = $widget.parent();
 
 				if ( $sidebar.parent().hasClass('closed') ) {
-					$sidebar.parent().removeClass('closed');
+					$sidebar.parent()
+						.removeClass( 'closed' )
+						.find( '.handlediv' ).attr( 'aria-expanded', 'true' );
+
 					$children = $sidebar.children('.widget');
 
 					// Make sure the dropped widget is at the top
@@ -622,8 +657,10 @@ wpWidgets = {
 			$( '#' + widgetId ).hide();
 		}
 
-		// Open the widgets container
+		// Open the widgets container.
-		sidebar.closest( '.widgets-holder-wrap' ).removeClass('closed');
+		sidebar.closest( '.widgets-holder-wrap' )
+			.removeClass( 'closed' )
+			.find( '.handlediv' ).attr( 'aria-expanded', 'true' );
 
 		sidebar.append( widget );
 		sidebar.sortable('refresh');
@@ -679,11 +716,14 @@ wpWidgets = {
 	 *
 	 * Used when a Widget gets dragged in/out of the Sidebar and never dropped.
 	 *
-	 * @param sidebar
+	 * @param {object} event jQuery event object.
 	 */
-	closeSidebar: function( sidebar ) {
+	closeSidebar: function( event ) {
-		this.hoveredSidebar.addClass( 'closed' );
+		this.hoveredSidebar
-		$( sidebar.target ).css( 'min-height', '' );
+			.addClass( 'closed' )
+			.find( '.handlediv' ).attr( 'aria-expanded', 'false' );
+
+		$( event.target ).css( 'min-height', '' );
 		this.hoveredSidebar = null;
 	}
 };

src/wp-admin/widgets.php

@@ -387,7 +387,10 @@ do_action( 'widgets_admin_page' ); ?>
 <div id="widgets-left">
 	<div id="available-widgets" class="widgets-holder-wrap">
 		<div class="sidebar-name">
-			<div class="sidebar-name-arrow"><br /></div>
+			<button type="button" class="handlediv hide-if-no-js" aria-expanded="true">
+				<span class="screen-reader-text"><?php _e( 'Available Widgets' ); ?></span>
+				<span class="toggle-indicator" aria-hidden="true"></span>
+			</button>
 			<h2><?php _e( 'Available Widgets' ); ?> <span id="removing-widget"><?php _ex( 'Deactivate', 'removing-widget' ); ?> <span></span></span></h2>
 		</div>
 		<div class="widget-holder">