Switch link list widgets to nav blocks

[joedolson]

Functionally, most of the widgets used in WordPress (archive links, categories list, tag cloud, recent posts, etc.) are nav blocks. Semantically, it would be sensible to mark them all as such and use aria-labelledby or aria-label to associate their context labels.

As a counter argument, adding the <nav> wrapper to these widgets is likely to have a) design consequences for themes and b) result in sites with large numbers of nav landmarks.

See thread: ​https://twitter.com/SaraSoueidan/status/1178015124076077056

There are arguments both for and against; it's something we should consider.

[afercia]

Worth also reminding widgets are wrapped in an aside element, which is not ideal. Exploring better semantic markup would be great.

[audrasjb]

Hi @afercia @joedolson

Most of these widgets are here for years, it would be very hard (= frankly impossible) to keep backward compatibility with all themes. I'd propose two alternative solutions for this issue:

• Keep the current markup but adding role="navigation" that doesn't hurt and it's still a good first step.
• Switch to <nav> for themes that declare HTML5 support for widgets.

I'd vote for the option 2. We just have to add a new option to the HTML5 features list.

For reference: ​https://developer.wordpress.org/reference/functions/add_theme_support/#html5

Cheers,
Jb

[audrasjb]

Moving to 5.5, as WP 5.4 beta 1 is in a couple of days.

[simonjanin]

I add the nav tag for widget menu, widget archives, widget categories, widget meta, widget pages, widget recent comments, widget recent posts and widget RSS by testing if add_theme_support function exists and get_theme_support( 'html5' ) exists.
With this nav tag, i add role navigation and an aria-label depending on the context.

[audrasjb]

Thanks for the patch @simonjanin, it looks like a pretty good basis.

Few considerations:

• Remove useless aria-label attributes.
• Use current_theme_supports functions rather than get_theme_support. For reference: ​https://developer.wordpress.org/reference/functions/current_theme_supports/
• Rather check if the theme supports html5 AND widget for backward compatibility. We should avoid to introduce too much breaking changes once this ticket is merged.

For reference, here is the current declaration themes can use to declare HTML5 compatibility/support:

add_theme_support( 'html5', array( 'comment-form', 'search-form', 'gallery', 'caption', 'style', 'script' ) );

Theme authors may want to declare HTML5 navigation widgets using this declaration:

add_theme_support( 'html5', array( 'comment-form', 'search-form', 'gallery', 'caption', 'style', 'script', 'navigation' ) );

You may want to update your patch to check this just like we currently do in get_search_form() function in Core (see wp-includes/general-template.php).

For example, do something like this:

$format = current_theme_supports( 'html5', 'search-form' ) ? '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 );

Then you can check for support using:

if ( 'html5' === $format ) { … }

Cheers,
Jb

[simonjanin]

Thanks @audrasjb for your advice and your indications.
I did what you said.
I upload a new diff file.

Bye,
Simon

[audrasjb]

Thanks @simonjanin, looks good to me!

I saw few coding standards issues.
Refreshed patch coming…

[audrasjb]

Coding standards fixes

[afercia]

Looking at 48170.3.diff​ it needs some refresh to avoid parse errors and meet the PHP coding standards. It's alwasy recommended to run PHPCS on the changed file :)

[audrasjb]

@afercia 48170.4.diff is a refreshed version of the previous patch. I think there should be other WPCS issues in the edited files, but not related to the changes introduced by this patch.

[audrasjb]

Patch refresh

[afercia]

48170.5.diff​ fixes the remaining PHPCS issues. Please double check.

Testing the patch, there's a main accessibility issue that should be fixed. All the <nav> elements are unlabelled. When there are multiple navigation landmarks on a page, those need to be labelled otherwise screen reader users would get a series of "navigation" landmarks with no clue what these landmarks are about. See screenshots.

To fix this, all the <nav> elements should use an aria-label attribute to give them a proper name:

• use the user-entered widget title
• if the user-entered widget title is empty, fallback to a meaningful title
• note that I think some of these widgets already use a fallback title (which may or may not be ideal)

Also:

• I see we're still using the pattern <nav role="navigation">: this is historically used to support old assistive technologies: do we still want to use the redundant role?
• is navigation a good name for the new HTML5 supported property?

[afercia]

Testing the widgets with nav elements on Twenty Twenty

[afercia]

The unlabelled navigation landmarks listed by a screen reader

[afercia]

48170.6.diff​:

• adds an aria-label to all the widgets that now use a nav element
• the aria-label is the widget title set in the admin and fallbacks to a default title, as an the aria-label always need to be populated
• RSS widget: uses the widget title stripping out the icon and links HTML

More importantly:
Since the Navigation Menu widget uses wp_nav_menu() under the hood, it modifies the previous approach. In fact, wp_nav_menu() can already use a <nav> element via the container argument. Thus, instead of using items_wrap:

• it uses container set to nav
• it adds a new argument container_aria_label to the wp_nav_menu() function $args, which is used only when container is nav
• the widget passes container_aria_label getting the value from the title set in the admin or a default string Menu

The dev-note should make sure to mention also the new wp_nav_menu() argument.

Some testing would be nice :)

[audrasjb]

Thanks for the new patch @afercia
Looks good on my side. I tested each navigation widget and it adds aria-label on each of them ⭐️

Note: I'll take care of the dev note for this change.

[afercia]

Screenshot to illustrate the default aria-labels on the new nav elements – Safari and VoiceOver

[afercia]

Thanks @audrasjb! Two minor points left here :)

• I see we're still using the pattern <nav role="navigation">: this is historically used to support old assistive technologies: do we still want to use the redundant role?
• Is navigation a good name for the new HTML5 supported property? As a developer, I'm not sure I would understand what it does from its name. No clue it relates to some widgets. Naming is hard.

[joedolson]

Continuing to include role="navigation" is harmless, from a functional standpoint, though it does throw warnings in HTML validation. It is probably time for us to decide when we're going to remove the use of role attributes to duplicate semantic functions like this, but I think that should be coordinated with the accessibility-ready theme guidelines. I think we should keep it for now, and make a plan for a timeline to remove them on a global basis at some point in the future. (Excepting role=list because Apple.)

Using 'navigation' as the property name kind of implies that this relates to menus, I think. Can we use 'widgets'? Doing some research on that seemed ambiguous; it's not listed as a property in the docs for ​add_theme_support, but is listed as a property under ​current_theme_supports in the codex. In general, I'm inclined to believe the new developer docs over info in the codex, but I couldn't find anything about what 'widgets' html5 support might mean right now, otherwise.

There are references in core to current_theme_supports( 'widgets' ), but not to current_theme_supports( 'html5', 'widgets' ).

[afercia]

I see some html5 supported "feature" use a name made of two words separated by a hyphen, e.g.:

• comment-form
• comment-list
• search-form

Wouldn't be better to follow this pattern to make clear it's about widgets as navigation landmarks?

[audrasjb]

Definitely makes sense to me. What about navigation-widgets ?

[audrasjb]

Introduce navigation-widgets HTML5 feature

[audrasjb]

@afercia patch refreshed.
Worth noting this also introduces consistency with navigation_widgets_format filter :)

[afercia]

In 48349:

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.

[johnbillion]

This change means the navigation_widgets_format filter is duplicated 8 times. The first instance should be the canonical reference, with the others referencing it.

[afercia]

Ugh thanks @johnbillion ! Yes only the first instance should have a complete docblock .All the other ones should have just a comment /** This filter is documented in {path to file here} */.

I guess it can be fixed during Beta, as it's about documentation.

[afercia]

In 48388:

Docs: Reference the documentation of the new navigation_widgets_format filter instead of repeating it.

Follow-up to [48349].

Props johnbillion.
Fixes #48170.

[SergeyBiryukov]

In 48410:

Widgets: Adjust formatting for displaying the closing </nav> tag in widgets for consistency with the opening tag.

Follow-up to [48349].

See #48170.

[justinahinon]

This was referenced in the following dev note ​https://make.wordpress.org/core/2020/07/09/accessibility-improvements-to-widgets-outputting-lists-of-links-in-5-5/

[justinahinon]

@afercia, @audrasjb I was wondering if there is a reason why this change has not been applied to the tags cloud widget.

[afercia]

@justinahinon good point. I'm not sure the tag-cloud widget was ever taken into consideration. @audrasjb may know more.

[audrasjb]

Indeed, we forgot the tag cloud.
Working on a patch right now. We should probably open a new ticket though

[audrasjb]

Patch proposed in #51455, thanks Justin!

[SergeyBiryukov]

In 49177:

Accessibility: Widgets: Conditionally wrap the tag cloud widget in a <nav> element.

If the theme declares support for the html5 feature navigation-widgets, the tag cloud widget is now wrapped in a <nav> element to improve semantics and accessibility.

The <nav> elements are native landmark regions, which helps assistive technology users to navigate through them.

Follow-up to [48349] for other widgets.

Props audrasjb, justinahinon, ravipatel.
Fixes #51455. See #48170.