Accessibility: Widgets: Add theme support to make widgets output list of links wrapped within a <nav> element.

Widgets that output list of links can now be wrapped within `<nav>` elements to improve semantics and accessibility.

The `<nav>` elements are also native landmark regions, which helps assistive technology users to navigate through them. Themes can opt-in to this new behavior by declaring support for the new `html5` feature `navigation-widgets`.

Props joedolson, simonjanin, audrasjb, afercia.
Fixes #48170.


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

src/wp-includes/nav-menu-template.php

@@ -15,6 +15,7 @@ require_once ABSPATH . WPINC . '/class-walker-nav-menu.php';
  *
  * @since 3.0.0
  * @since 4.7.0 Added the `item_spacing` argument.
+ * @since 5.5.0 Added the `container_aria_label` argument.
  *
  * @param array $args {
  *     Optional. Array of nav menu arguments.
@@ -26,6 +27,7 @@ require_once ABSPATH . WPINC . '/class-walker-nav-menu.php';
  *     @type string             $container            Whether to wrap the ul, and what to wrap it with. Default 'div'.
  *     @type string             $container_class      Class that is applied to the container. Default 'menu-{menu slug}-container'.
  *     @type string             $container_id         The ID that is applied to the container. Default empty.
+ *     @type string             $container_aria_label The aria-label attribute that is applied to the container when it's a nav element. Default empty.
  *     @type callable|bool      $fallback_cb          If the menu doesn't exist, a callback function will fire.
  *                                                    Default is 'wp_page_menu'. Set to false for no fallback.
  *     @type string             $before               Text before the link markup. Default empty.
@@ -52,6 +54,7 @@ function wp_nav_menu( $args = array() ) {
 		'container'            => 'div',
 		'container_class'      => '',
 		'container_id'         => '',
+		'container_aria_label' => '',
 		'menu_class'           => 'menu',
 		'menu_id'              => '',
 		'echo'                 => true,
@@ -176,7 +179,8 @@ function wp_nav_menu( $args = array() ) {
 			$show_container = true;
 			$class          = $args->container_class ? ' class="' . esc_attr( $args->container_class ) . '"' : ' class="menu-' . $menu->slug . '-container"';
 			$id             = $args->container_id ? ' id="' . esc_attr( $args->container_id ) . '"' : '';
-			$nav_menu      .= '<' . $args->container . $id . $class . '>';
+			$aria_label     = ( 'nav' === $args->container && $args->container_aria_label ) ? ' aria-label="' . esc_attr( $args->container_aria_label ) . '"' : '';
+			$nav_menu      .= '<' . $args->container . $id . $class . $aria_label . '>';
 		}
 	}
 

src/wp-includes/widgets/class-wp-nav-menu-widget.php

@@ -46,6 +46,7 @@ class WP_Nav_Menu_Widget extends WP_Widget {
 			return;
 		}
 
+		$default_title = __( 'Menu' );
 		$title         = ! empty( $instance['title'] ) ? $instance['title'] : '';
 
 		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
@@ -57,10 +58,36 @@ class WP_Nav_Menu_Widget extends WP_Widget {
 			echo $args['before_title'] . $title . $args['after_title'];
 		}
 
+		$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+		/**
+		 * Filters the HTML format of widgets with navigation links.
+		 *
+		 * @since 5.5.0
+		 *
+		 * @param string $format The type of markup to use in widgets with navigation links.
+		 *                       Accepts 'html5', 'xhtml'.
+		 */
+		$format = apply_filters( 'navigation_widgets_format', $format );
+
+		if ( 'html5' === $format ) {
+			// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+			$title      = trim( strip_tags( $title ) );
+			$aria_label = $title ? $title : $default_title;
+
+			$nav_menu_args = array(
+				'fallback_cb'          => '',
+				'menu'                 => $nav_menu,
+				'container'            => 'nav',
+				'container_aria_label' => $aria_label,
+				'items_wrap'           => '<ul id="%1$s" class="%2$s">%3$s</ul>',
+			);
+		} else {
 			$nav_menu_args = array(
 				'fallback_cb' => '',
 				'menu'        => $nav_menu,
 			);
+		}
 
 		/**
 		 * Filters the arguments for the Navigation Menu widget.

src/wp-includes/widgets/class-wp-widget-archives.php

@@ -40,7 +40,8 @@ class WP_Widget_Archives extends WP_Widget {
 	 * @param array $instance Settings for the current Archives widget instance.
 	 */
 	public function widget( $args, $instance ) {
-		$title = ! empty( $instance['title'] ) ? $instance['title'] : __( 'Archives' );
+		$default_title = __( 'Archives' );
+		$title         = ! empty( $instance['title'] ) ? $instance['title'] : $default_title;
 
 		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
 		$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
@@ -120,8 +121,28 @@ class WP_Widget_Archives extends WP_Widget {
 })();
 /* ]]> */
 </script>
+			<?php
+		} else {
+			$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+			/**
+			 * Filters the HTML format of widgets with navigation links.
+			 *
+			 * @since 5.5.0
+			 *
+			 * @param string $format The type of markup to use in widgets with navigation links.
+			 *                       Accepts 'html5', 'xhtml'.
+			 */
+			$format = apply_filters( 'navigation_widgets_format', $format );
+
+			if ( 'html5' === $format ) {
+				// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+				$title      = trim( strip_tags( $title ) );
+				$aria_label = $title ? $title : $default_title;
+				echo '<nav role="navigation" aria-label="' . esc_attr( $aria_label ) . '">';
+			}
+			?>
 
-		<?php } else { ?>
 			<ul>
 				<?php
 				wp_get_archives(
@@ -147,11 +168,14 @@ class WP_Widget_Archives extends WP_Widget {
 				);
 				?>
 			</ul>
-			<?php
+			<?php if ( 'html5' === $format ) : ?>
-		}
+				</nav>
+			<?php endif; ?>
 
+			<?php
 			echo $args['after_widget'];
 		}
+	}
 
 	/**
 	 * Handles updating settings for the current Archives widget instance.

src/wp-includes/widgets/class-wp-widget-categories.php

@@ -44,7 +44,8 @@ class WP_Widget_Categories extends WP_Widget {
 	public function widget( $args, $instance ) {
 		static $first_dropdown = true;
 
-		$title = ! empty( $instance['title'] ) ? $instance['title'] : __( 'Categories' );
+		$default_title = __( 'Categories' );
+		$title         = ! empty( $instance['title'] ) ? $instance['title'] : $default_title;
 
 		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
 		$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
@@ -109,7 +110,26 @@ class WP_Widget_Categories extends WP_Widget {
 
 			<?php
 		} else {
+			$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+			/**
+			 * Filters the HTML format of widgets with navigation links.
+			 *
+			 * @since 5.5.0
+			 *
+			 * @param string $format The type of markup to use in widgets with navigation links.
+			 *                       Accepts 'html5', 'xhtml'.
+			 */
+			$format = apply_filters( 'navigation_widgets_format', $format );
+
+			if ( 'html5' === $format ) {
+				// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+				$title      = trim( strip_tags( $title ) );
+				$aria_label = $title ? $title : $default_title;
+				echo '<nav role="navigation" aria-label="' . esc_attr( $aria_label ) . '">';
+			}
 			?>
+
 			<ul>
 				<?php
 				$cat_args['title_li'] = '';
@@ -126,6 +146,11 @@ class WP_Widget_Categories extends WP_Widget {
 				wp_list_categories( apply_filters( 'widget_categories_args', $cat_args, $instance ) );
 				?>
 			</ul>
+
+			<?php if ( 'html5' === $format ) : ?>
+				</nav>
+			<?php endif; ?>
+
 			<?php
 		}
 

src/wp-includes/widgets/class-wp-widget-meta.php

@@ -42,7 +42,8 @@ class WP_Widget_Meta extends WP_Widget {
 	 * @param array $instance Settings for the current Meta widget instance.
 	 */
 	public function widget( $args, $instance ) {
-		$title = ! empty( $instance['title'] ) ? $instance['title'] : __( 'Meta' );
+		$default_title = __( 'Meta' );
+		$title         = ! empty( $instance['title'] ) ? $instance['title'] : $default_title;
 
 		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
 		$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
@@ -52,12 +53,34 @@ class WP_Widget_Meta extends WP_Widget {
 		if ( $title ) {
 			echo $args['before_title'] . $title . $args['after_title'];
 		}
+
+		$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+		/**
+		 * Filters the HTML format of widgets with navigation links.
+		 *
+		 * @since 5.5.0
+		 *
+		 * @param string $format The type of markup to use in widgets with navigation links.
+		 *                       Accepts 'html5', 'xhtml'.
+		 */
+		$format = apply_filters( 'navigation_widgets_format', $format );
+
+		if ( 'html5' === $format ) {
+			// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+			$title      = trim( strip_tags( $title ) );
+			$aria_label = $title ? $title : $default_title;
+			echo '<nav role="navigation" aria-label="' . esc_attr( $aria_label ) . '">';
+		}
 		?>
+
+
 		<ul>
 			<?php wp_register(); ?>
 			<li><?php wp_loginout(); ?></li>
 			<li><a href="<?php echo esc_url( get_bloginfo( 'rss2_url' ) ); ?>"><?php _e( 'Entries feed' ); ?></a></li>
 			<li><a href="<?php echo esc_url( get_bloginfo( 'comments_rss2_url' ) ); ?>"><?php _e( 'Comments feed' ); ?></a></li>
+
 			<?php
 			/**
 			 * Filters the "WordPress.org" list item HTML in the Meta widget.
@@ -80,9 +103,14 @@ class WP_Widget_Meta extends WP_Widget {
 
 			wp_meta();
 			?>
-			</ul>
-			<?php
 
+		</ul>
+
+		<?php if ( 'html5' === $format ) : ?>
+			</nav>
+		<?php endif; ?>
+
+		<?php
 		echo $args['after_widget'];
 	}
 

src/wp-includes/widgets/class-wp-widget-pages.php

@@ -40,7 +40,8 @@ class WP_Widget_Pages extends WP_Widget {
 	 * @param array $instance Settings for the current Pages widget instance.
 	 */
 	public function widget( $args, $instance ) {
-		$title = ! empty( $instance['title'] ) ? $instance['title'] : __( 'Pages' );
+		$default_title = __( 'Pages' );
+		$title         = ! empty( $instance['title'] ) ? $instance['title'] : $default_title;
 
 		/**
 		 * Filters the widget title.
@@ -89,10 +90,35 @@ class WP_Widget_Pages extends WP_Widget {
 			if ( $title ) {
 				echo $args['before_title'] . $title . $args['after_title'];
 			}
+
+			$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+			/**
+			 * Filters the HTML format of widgets with navigation links.
+			 *
+			 * @since 5.5.0
+			 *
+			 * @param string $format The type of markup to use in widgets with navigation links.
+			 *                       Accepts 'html5', 'xhtml'.
+			 */
+			$format = apply_filters( 'navigation_widgets_format', $format );
+
+			if ( 'html5' === $format ) {
+				// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+				$title      = trim( strip_tags( $title ) );
+				$aria_label = $title ? $title : $default_title;
+				echo '<nav role="navigation" aria-label="' . esc_attr( $aria_label ) . '">';
+			}
 			?>
+
 			<ul>
 				<?php echo $out; ?>
 			</ul>
+
+			<?php if ( 'html5' === $format ) : ?>
+				</nav>
+			<?php endif; ?>
+
 			<?php
 			echo $args['after_widget'];
 		}

src/wp-includes/widgets/class-wp-widget-recent-comments.php

@@ -82,7 +82,8 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 
 		$output = '';
 
-		$title = ( ! empty( $instance['title'] ) ) ? $instance['title'] : __( 'Recent Comments' );
+		$default_title = __( 'Recent Comments' );
+		$title         = ( ! empty( $instance['title'] ) ) ? $instance['title'] : $default_title;
 
 		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
 		$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
@@ -123,6 +124,25 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 		$recent_comments_id = ( $first_instance ) ? 'recentcomments' : "recentcomments-{$this->number}";
 		$first_instance     = false;
 
+		$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+		/**
+		 * Filters the HTML format of widgets with navigation links.
+		 *
+		 * @since 5.5.0
+		 *
+		 * @param string $format The type of markup to use in widgets with navigation links.
+		 *                       Accepts 'html5', 'xhtml'.
+		 */
+		$format = apply_filters( 'navigation_widgets_format', $format );
+
+		if ( 'html5' === $format ) {
+			// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+			$title      = trim( strip_tags( $title ) );
+			$aria_label = $title ? $title : $default_title;
+			$output    .= '<nav role="navigation" aria-label="' . esc_attr( $aria_label ) . '">';
+		}
+
 		$output .= '<ul id="' . esc_attr( $recent_comments_id ) . '">';
 		if ( is_array( $comments ) && $comments ) {
 			// Prime cache for associated posts. (Prime post term cache if we need it for permalinks.)
@@ -141,6 +161,11 @@ class WP_Widget_Recent_Comments extends WP_Widget {
 			}
 		}
 		$output .= '</ul>';
+
+		if ( 'html5' === $format ) {
+			$output .= '</nav>';
+		}
+
 		$output .= $args['after_widget'];
 
 		echo $output;

src/wp-includes/widgets/class-wp-widget-recent-posts.php

@@ -45,7 +45,8 @@ class WP_Widget_Recent_Posts extends WP_Widget {
 			$args['widget_id'] = $this->id;
 		}
 
-		$title = ( ! empty( $instance['title'] ) ) ? $instance['title'] : __( 'Recent Posts' );
+		$default_title = __( 'Recent Posts' );
+		$title         = ( ! empty( $instance['title'] ) ) ? $instance['title'] : $default_title;
 
 		/** This filter is documented in wp-includes/widgets/class-wp-widget-pages.php */
 		$title = apply_filters( 'widget_title', $title, $instance, $this->id_base );
@@ -84,12 +85,34 @@ class WP_Widget_Recent_Posts extends WP_Widget {
 			return;
 		}
 		?>
+
 		<?php echo $args['before_widget']; ?>
+
 		<?php
 		if ( $title ) {
 			echo $args['before_title'] . $title . $args['after_title'];
 		}
+
+		$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+		/**
+		 * Filters the HTML format of widgets with navigation links.
+		 *
+		 * @since 5.5.0
+		 *
+		 * @param string $format The type of markup to use in widgets with navigation links.
+		 *                       Accepts 'html5', 'xhtml'.
+		 */
+		$format = apply_filters( 'navigation_widgets_format', $format );
+
+		if ( 'html5' === $format ) {
+			// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+			$title      = trim( strip_tags( $title ) );
+			$aria_label = $title ? $title : $default_title;
+			echo '<nav role="navigation" aria-label="' . esc_attr( $aria_label ) . '">';
+		}
 		?>
+
 		<ul>
 			<?php foreach ( $r->posts as $recent_post ) : ?>
 				<?php
@@ -109,6 +132,10 @@ class WP_Widget_Recent_Posts extends WP_Widget {
 				</li>
 			<?php endforeach; ?>
 		</ul>
+		<?php if ( 'html5' === $format ) : ?>
+			</nav>
+		<?php endif; ?>
+
 		<?php
 		echo $args['after_widget'];
 	}

src/wp-includes/widgets/class-wp-widget-rss.php

@@ -94,7 +94,32 @@ class WP_Widget_RSS extends WP_Widget {
 		if ( $title ) {
 			echo $args['before_title'] . $title . $args['after_title'];
 		}
+
+		$format = current_theme_supports( 'html5', 'navigation-widgets' ) ? 'html5' : 'xhtml';
+
+		/**
+		 * Filters the HTML format of widgets with navigation links.
+		 *
+		 * @since 5.5.0
+		 *
+		 * @param string $format The type of markup to use in widgets with navigation links.
+		 *                       Accepts 'html5', 'xhtml'.
+		 */
+		$format = apply_filters( 'navigation_widgets_format', $format );
+
+		if ( 'html5' === $format ) {
+			// The title may be filtered: Strip out HTML and make sure the aria-label is never empty.
+			$title      = trim( strip_tags( $title ) );
+			$aria_label = $title ? $title : __( 'RSS Feed' );
+			echo '<nav role="navigation" aria-label="' . esc_attr( $aria_label ) . '">';
+		}
+
 		wp_widget_rss_output( $rss, $instance );
+
+		if ( 'html5' === $format ) {
+			echo '</nav>';
+		}
+
 		echo $args['after_widget'];
 
 		if ( ! is_wp_error( $rss ) ) {