Site editor: Fix the document title announcement for screen readers

[afercia]

Description

Alternative to https://github.com/WordPress/gutenberg/pull/56167

The Site Editor uses a 'single page app' navigation type, where navigating through the different views of the editor updates the content of the page but the HTML document is always the same. As such, like in all single page apps, the navigation needs to be announced bt screen readers to emulate the native beheavir of a traditional navigation across different pages, where the document title is announced as first thing.

The current implementation in the Site editor uses a speak() to announce the updated document title and the site title, also appending the string WordPress:

https://github.com/WordPress/gutenberg/blob/dc7e1aa202ee2605f0423ac0f48fa590b3027f60/packages/edit-site/src/components/routes/use-title.js#L38-L58

There's a few problems though:

• Sometimes, the document title doesn't actually reflect the displayed view. For example, the initial view is called 'Design' but the current state of the editor is displaying the Home bloc template. The document title is <title>Blog Home ‹ Template ‹ Editor ‹ WordPress Develop — WordPress</title> and that gets announced, which is misleading and doesn't reflect what is shown visually.
• When navigating to some page, the document title doesn't change. For example clicking on 'Templates', I would expect the document title to tell me I'm in the Templages page. Intead, it is still <title>Blog Home ‹ Template ‹ Editor ‹ WordPress Develop — WordPress</title>. This gets announced by screen readers and it's just wrong.
• The same thing happens when clicking on Navigation, Styles, Pages, or Patterns: the document title is not announced so the audible feedback is just wrong. It appears all 'first level' pages in the routing mechanism don't update the document title correctly.
• The announcement is too verbose anyways. For example, when navigating to the 'Single posts' template page, as a screen reader user I just need to know that the navigation completed succesfully and I'm now in the Single Posts view. Insteead, the announcement is really too long and annoying: Now displaying: Single Posts ‹ Template ‹ Editor ‹ WordPress Develop — WordPress

Suggested remediation:

• Make sure the document title is always updated.
• Make sure the document title always accurately reflects what the current view is.
• Shorten the audibel message and strip out the part ‹ Editor ‹ WordPress Develop — WordPress.

Step-by-step reproduction instructions

• Test with a screen reader. For this issue, using Safari and VoiceOver is sufficient. On Windows, you can try Firefox and NVDA.
• Go to the Site editor and navigate through the site editor views.
• Observe the navigation announcement is incorrect for the first level views.
• Observe the announcement is too verbose and annoying.

Screenshots, screen recording, code snippet

Wrong document title announced on the Templates view:

Wrong document title announced on the Navigation view:

Example of too verbose announcement:

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[alexstine]

@afercia How would you feel about completely eliminating this message? My PR does just that. #56167. We now have progress bar to communicate loading state and the heading structure is much improved for context. I see this as being much less of an issue compared to the beginning of FSE.

[afercia]

@alexstine I'm not sure entirely removing these announcements would be good for all users.

We now have progress bar to communicate loading state

I had a look at the progressbar implementation and I doubt it can work correctly as it misses some important attributes like aria-valuenow. Also, when used as a loading indicator, the progressbar should be responsible to set aria-busy on the region that is being loaded. All this is well explained in the spec but I don't see any of that in the current code. Regardless, testing with Safari and VoiceOver, I don't get any progress announcement. We should create an issue to fix the progressbar.

and the heading structure is much improved for context.

Yes that is improved but I'm not sure it is sufficient. When testing https://github.com/WordPress/gutenberg/pull/56167 upon navigation the announcement would only tell something about the back button. Something like:

Back, button, Navigation, region

and nothing else, which isn't great, in my opinion.

[alexstine]

I'll make a follow-up to fix Progressbar. I thought we covered everything there but guess not. 😞 Testing in Storybook and site editor produced two different results I suppose.

[alexstine]

@kevin940726 or @youknowriad Can you offer up any ideas on what might be setting incorrect page titles in the site editor?

Make sure the document title always accurately reflects what the current view is.

I traced through the selectors and it looks like it tries to make a guess based off of template name and template type but the home page of the site editor should be neither of those. Need some custom fallback logic? I bet it's getting a default set somewhere and that's what makes it return the wrong page when the proper context can't be found.

[youknowriad]

I think at the moment the useTitle call is within the "Editor" component and is using the title from the useEditedEntityRecord hook. Which means it's showing the title of the parent template for the pages that show "pages within their templates". That's probably causing some issues.

The other thing is that as written today the "title" is guessed from the edited entity in the editor but in a lot of site editor pages, we always show the home page but the sidebar is different (templates, ...) so it makes more sense to tie the "title" to the "routing" instead.

To be honest, the routing as implemented today in the site editor is very basic and adhoc and not well organized. I know @kevin940726 has started some explorations to improve the situations, maybe just a poc for now. But we will solve this properly once we have a solid routing system in place I think.

[alexstine]

@youknowriad Yeah, being able to properly tie the title to the path is likely a better solution going forward. I will not attempt to fix that in my PR, I will simply shorten the title as requested and leave this issue open for reference. Looks like this is going to be a much bigger effort than accessibility alone.

Thanks.