WordPress.org

Make WordPress Core

Opened 10 months ago

Closed 4 weeks ago

Last modified 3 weeks ago

#48170 closed enhancement (fixed)

Switch link list widgets to nav blocks

Reported by: joedolson Owned by: audrasjb
Milestone: 5.5 Priority: normal
Severity: normal Version:
Component: Widgets Keywords: needs-patch has-dev-note
Focuses: accessibility Cc:

Description

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.

Attachments (10)

48170.diff (9.5 KB) - added by simonjanin 3 months ago.
48170.2.diff (11.3 KB) - added by simonjanin 2 months ago.
48170.3.diff (12.9 KB) - added by audrasjb 2 months ago.
Coding standards fixes
48170.4.diff (11.7 KB) - added by audrasjb 5 weeks ago.
Patch refresh
48170.5.diff (11.3 KB) - added by afercia 5 weeks ago.
48170 navs widgets.png (270.9 KB) - added by afercia 5 weeks ago.
Testing the widgets with nav elements on Twenty Twenty
48170 unlabelled navs.png (307.9 KB) - added by afercia 5 weeks ago.
The unlabelled navigation landmarks listed by a screen reader
48170.6.diff (23.5 KB) - added by afercia 4 weeks ago.
48170 labeled nav landmarks.jpg (195.8 KB) - added by afercia 4 weeks ago.
Screenshot to illustrate the default aria-labels on the new nav elements – Safari and VoiceOver
48170.7.diff (23.6 KB) - added by audrasjb 4 weeks ago.
Introduce navigation-widgets HTML5 feature

Download all attachments as: .zip

Change History (45)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.


9 months ago

#2 @afercia
9 months ago

  • Keywords needs-patch added
  • Milestone changed from Awaiting Review to 5.4

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

#3 @audrasjb
7 months ago

  • Owner changed from joedolson to audrasjb
  • Status changed from assigned to accepted

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

This ticket was mentioned in Slack in #accessibility by audrasjb. View the logs.


6 months ago

#5 @audrasjb
6 months ago

  • Milestone changed from 5.4 to 5.5

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

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.


3 months ago

@simonjanin
3 months ago

#7 @simonjanin
3 months ago

  • Keywords has-patch added; needs-patch removed

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.

#8 @audrasjb
3 months ago

  • Keywords needs-refresh added

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

Few considerations:

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
2 months ago

#9 @simonjanin
2 months ago

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

Bye,
Simon

#10 @audrasjb
2 months ago

Thanks @simonjanin, looks good to me!

I saw few coding standards issues.
Refreshed patch coming…

@audrasjb
2 months ago

Coding standards fixes

#11 @audrasjb
2 months ago

  • Keywords dev-feedback added; needs-refresh removed

This ticket was mentioned in Slack in #accessibility by audrasjb. View the logs.


2 months ago

#13 @afercia
8 weeks ago

  • Keywords needs-refresh added

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 :)

This ticket was mentioned in Slack in #accessibility by afercia. View the logs.


8 weeks ago

This ticket was mentioned in Slack in #accessibility by audrasjb. View the logs.


6 weeks ago

#16 @audrasjb
6 weeks ago

  • Keywords needs-dev-note added

This ticket was mentioned in Slack in #accessibility by audrasjb. View the logs.


5 weeks ago

#18 @audrasjb
5 weeks ago

  • Keywords needs-refresh removed

@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
5 weeks ago

Patch refresh

@afercia
5 weeks ago

#19 @afercia
5 weeks ago

  • Keywords dev-feedback removed

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
5 weeks ago

Testing the widgets with nav elements on Twenty Twenty

@afercia
5 weeks ago

The unlabelled navigation landmarks listed by a screen reader

@afercia
4 weeks ago

#20 @afercia
4 weeks ago

  • Keywords commit added

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 :)

#21 @audrasjb
4 weeks ago

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
4 weeks ago

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

#22 @afercia
4 weeks ago

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.

#23 @joedolson
4 weeks ago

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' ).

#24 @afercia
4 weeks ago

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?

#25 @audrasjb
4 weeks ago

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

This ticket was mentioned in Slack in #accessibility by audrasjb. View the logs.


4 weeks ago

#27 @audrasjb
4 weeks ago

  • Keywords needs-refresh added

@audrasjb
4 weeks ago

Introduce navigation-widgets HTML5 feature

#28 @audrasjb
4 weeks ago

  • Keywords needs-refresh removed

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

#29 @afercia
4 weeks ago

  • Resolution set to fixed
  • Status changed from accepted to closed

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.

#30 @johnbillion
4 weeks ago

  • Keywords needs-patch added; has-patch commit removed
  • Resolution fixed deleted
  • Status changed from closed to reopened

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.

#31 @afercia
4 weeks ago

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.

#32 @afercia
4 weeks ago

  • Resolution set to fixed
  • Status changed from reopened to closed

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.

#33 @SergeyBiryukov
4 weeks ago

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.

#34 @audrasjb
4 weeks ago

  • Keywords has-dev-note added; needs-dev-note removed
Note: See TracTickets for help on using tickets.