Allow :focus-visible pseudo-selector to be set in theme.json

[huubl]

Fixes #68520

What?

This PR adds support for the :focus-visible pseudo-class in theme.json by including it in the VALID_ELEMENT_PSEUDO_SELECTORS list.

Why?

Currently, the :focus-visible pseudo-class cannot be set via theme.json because it is not included in the VALID_ELEMENT_PSEUDO_SELECTORS list. This limitation makes it difficult to implement enhanced focus styles specifically for keyboard users, impacting accessibility. Adding :focus-visible will allow themes to provide better focus indicators, improving the overall user experience for keyboard navigation.

How?

The PR updates the VALID_ELEMENT_PSEUDO_SELECTORS array in class-wp-theme-json-gutenberg.php by adding :focus-visible. This change allows the :focus-visible pseudo-class to be used directly within theme.json files.

Testing Instructions

1. Apply this PR.
2. Create or edit a theme that uses theme.json.
3. Add a style using the :focus-visible pseudo-class in theme.json. For example:

{
	"styles": {
		"elements": {
			"button": {
				"color": {
					"background": "black",
					"text": "white"
				},
				":focus": {
					"outline": {
						"color": "green",
						"offset": "5px"
					}
				},
				":focus-visible": {
					"outline": {
						"color": "red",
						"style": "dotted"
					}
				}
			}
		}
	}
}

Testing Instructions for Keyboard

Screenshots or screencast

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: huubl <huubl@git.wordpress.org>
Co-authored-by: carolinan <poena@git.wordpress.org>
Co-authored-by: audrasjb <audrasjb@git.wordpress.org>
Co-authored-by: joedolson <joedolson@git.wordpress.org>
Co-authored-by: sabernhardt <sabernhardt@git.wordpress.org>
Co-authored-by: afercia <afercia@git.wordpress.org>
Co-authored-by: Bovelett <annebovelett@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[carolinan]

I think we should include this.
The changes to the PHP file needs to be backported to WordPress, so a new trac ticket and PR needs to be created and the changelog entry needs to be added.

[huubl]

I think we should include this. The changes to the PHP file needs to be backported to WordPress, so a new trac ticket and PR needs to be created and the changelog entry needs to be added.

Hi @carolinan,

I created a trac ticket and created a pull request to wordpress-develop. But not sure what to do for "the changelog entry needs to be added"?

[carolinan]

I am testing this again today and I am not able to make it work. It doesn't look like the correct CSS for :focus-visible is being printed.
Can you update the testing instructions including what the expected result is (I mean, the style should change when a button is focused on but not when it is clicked)

[carolinan]

If you look at the test results, there is an item that says "verify core backport changelog". If you open the details, it says:
See backport-changelog/readme.md for more information.

https://github.com/WordPress/gutenberg/blob/trunk/backport-changelog/readme.md

[carolinan]

Do you think the order may be wrong?

'link'   => array( ':link', ':any-link', ':visited', ':hover', ':focus', ':focus-visible', ':active' ),
'button' => array( ':link', ':any-link', ':visited', ':hover', ':focus', ':focus-visible', ':active' ),

Pinging @sabernhardt for your expertise 😄

[sabernhardt]

Thanks for asking. My expertise with this list just involves moving :visited earlier in Trac 56928, bringing it closer to the "LoVe (F)HA" sequence.

To me, putting :focus-visible after :focus seems reasonable. If someone defines styles for both, and the two disagree somehow, I would think the less common :focus-visible style is more likely what the designer intended.

However, my quick test did not behave exactly as I expected.

• When using the Tab key to navigate from one element to another, the outline style matched the ruleset that came later for all three types of elements.
• When I clicked on each element, the text inputs matched the later ruleset styling again, but the links and buttons used the :focus styles regardless of the cascade order.

[afercia]

• When I clicked on each element, the text inputs matched the later ruleset styling again, but the links and buttons used the :focus styles regardless of the cascade order.

A potential source of confusion may be that the quick test uses outline for both :focus and focus:visible. Whatever of the two prevails, it will override the other outline. By using different properties, the actual behavior becomes clearer. See this codepen.

Reading the MDN page about focucs-visible, today I learned that the browser heuristics to determine whether to use focus-visible isn't just about pointing device or keyboard. It's when the browser decides that the element needs user attention.

For instance, when a button is clicked using a pointing device, the focus is generally not visually indicated, but when a text box needing user input has focus, focus is indicated.

In fact, the W3C Selectors Level 4 spec doesn't mention any specific device.

... using a variety of heuristics to visibly indicate the focus only when it would be most helpful to the user.

So it appears that 'most helpful to the user' always includes input fields.
In the test codepen, focus-visible is applied to the inputs also when clicking with the mouse. It is not on the links and buttons.
When using the keyboard, both styles are applied on all elements.

[audrasjb]

Added to the 6.8 project board so we can update this on Gutenberg alongside Trac ticket 62906.

[carolinan]

Is the conclusion that it is working as long as there is no focus style?
Is that what we want? I think other developers would be as confused as us as to why it is not working out of the box, without having to remove other styles?

[huubl]

I am testing this again today and I am not able to make it work. It doesn't look like the correct CSS for :focus-visible is being printed. Can you update the testing instructions including what the expected result is (I mean, the style should change when a button is focused on but not when it is clicked)

@carolinan, can you test it again and review my last commit?

I think the order in VALID_ELEMENT_PSEUDO_SELECTORS is correct and the :focus-visible css should overrule :focus. But I found that the :focus-visible output was wrongly matched to :focus, because :focus is found first in e.g. ".wp-element-button:focus-visible". I changed the check to ensure the match is not followed by a dash.

[carolinan]

Thank you for the update, I think it is working now.
With the sample code added to theme.json, the buttons have a red dotted outline when I navigate to them using the keyboard, but a green solid outline when I click on them with the mouse.

[joedolson]

The related core ticket (https://core.trac.wordpress.org/ticket/62906) is merged.