Support pseudo selectors on elements in theme json

[getdave]

What?

As part of work towards #38277, this PR enables theme.json support for elements (both top and block level) to contain pseudo selectors in the form:

{
    "elements": {
        "link": {
            "color": {
                "text": "green"
            },
            ":hover": {
                "color": {
                    "text": "hotpink"
                }
            }
        }
    },
    "blocks": {
        "core/group": {
             "elements": {
                "link": {
                    ":hover": {
                        "color": {
                            "text": "red"
                        }
                    }
                }
            }
        }
    }
}

Currently this PR imposes a whitelist which governs which psuedo selectors are available to be used on which elements. It looks like this but could be augmented as required:

const VALID_ELEMENT_PSEUDO_SELECTORS = array(
    'link' => array( ':hover', ':focus' ),
);

Please note that once an element is "open" to a given pseudo selector all valid stlye properties are available to be changed. For example the following is valid whether you should do it or not:

{
    "elements": {
        "link": {
            "color": {
                "text": "green"
            },
            ":hover": {
                "color": {
                    "text": "hotpink"
                },
                "typography": {
                    "textTransform": "uppercase",
                    "fontSize": "10em"
                }
            }
        }
    }
}

My personal preference would be to lock things down to a bear minimum to avoid a11y issues but I guess perhaps we'll want things open to developers to make those choices just like they do every day in CSS. We can limit user choices but choosing not to expose UI controls for every possible style property.

Why?

This is low level work to support styling of interactivity states in the editor and front end.

How?

Update the sanitization routines to allow various pseudo selectors on a per element basis. For now we only support link.

Todo

• Get WP_Theme_JSON_Gutenberg::remove_insecure_properties to allow for pseudo selectors.
• Ensure pseudo selectors end up in final processed theme json
• Ensure correct styles are generated for pseudo selectors from the theme json in editor.
• Ensure correct styles are generated for pseudo selectors from the theme json on front end.
• Consider enabling block-level elements pseudo selector support.
• Learn how to type/spell pseudo (note: this task will never be completed)
• Add/augment automated tests.
• Create an allow/whitelist for per element pseudo selectors for use on client side (or pass the existing config value from PHP) - this can be handled in a followup.
• Augment frontend JS global styles tests to assert on pseudo selector generation.
• Refine PR desc and make RfR

Testing Instructions

Stress testing

Note this PR is being stress tested by applying it various Themes.

Testing with Archeo test PR

I have created an example PR on the Archeo theme to test this out. You can try that by running a copy of Archeo with that PR checked out.

Manual testing

• Use a Theme where you can modify the theme.json file.
• Try adding some psudo selector styles for link element at top level:

{
    "elements": {
        "link": {
            "color": {
                "text": "green"
            },
            ":hover": {
                "color": {
                    "text": "hotpink"
                }
            }
        }
    }
}

• validate standard a elements have a hotpink color when you hover over them on both editor and frontend.
• now add an invalid pseudo selector and check it isn't output in the stylesheet

{
    "elements": {
        "link": {
            "color": {
                "text": "green"
            },
            ":thisisaninvalidselector": {
                "color": {
                    "text": "hotpink"
                }
            }
        }
    }
}

• following the same pattern as above now try adding an unsupported selector such as :target.
• following the same pattern as above now try adding an unsupported element like button.

{
    "elements": {
        "button": {
            "color": {
                "text": "green"
            },
            ":hover": {
                "color": {
                    "text": "hotpink"
                }
            }
        }
    }
}

Please be sure to check in both the Post and the Site Editor.

Screenshots or screencast

Editor

Frontend

Authors

Co-authored-by: Andrei Draganescu <me@andreidraganescu.info>, Adam Zielinski, Ben Dwyer <ben@scruffian.com>

[getdave]

Here we add a new sub item for each pseudo selector to the schema for each element (e.g. link, h1...etc). Each selector is the key with the valid style values as the value.

[getdave]

We should remove this or add as a comment above the relevant places.

[getdave]

This line is why we need to update the schema to allow for pseudo selectors.

[getdave]

I think we can safely remove this function and leave it to the version in WP Core. We've not modified it right?

[ramonjd]

If it's not been modified between 5.9 and 6.0 I think so, though I'd hate to be quoted on that 😄

Should we wait for this PR first? #41306

Is there a reason why it's in 6.1 here if it's not been altered?

[getdave]

Added - here we check whether the current element is in the allowed list for pseudo selectors.

If it is then we loop over all the whitelisted selectors for the given element and append them to the output (having first removed insecure styles as for "normal" properties).

This allows for the following structure to be returned from remove_insecure_properties:

array(
    'styles'  => array(
        'elements' => array(
            'link' => array(
                'color'  => array(
                    'text'       => 'hotpink',
                    'background' => 'yellow',
                ),
                ':hover' => array(
                    'color' => array(
                        'text'       => 'red',
                        'background' => 'blue',
                    ),
                ),
            ),
        ),
    ),
);

Without this change the :hover key would not be preserved.

[ramonjd]

If it's not been modified between 5.9 and 6.0 I think so, though I'd hate to be quoted on that 😄

Should we wait for this PR first? #41306

Is there a reason why it's in 6.1 here if it's not been altered?

[ramonjd]

Learn how to type/spell pseudo

When you do, can you teach me? 😄

Currently the pseudo selector rules are not being output in the Site Editor. It all works in the Post Editor and also o the front end.

This might be a long shot, but I was also having trouble with overwriting core's get_block_editor_settings() in Gutenberg

#39529 (comment)

[ramonjd]

Please note that once an element is "open" to a given pseudo selector all valid stlye properties are available to be changed.

If this is limited to theme.json, and not available to controls via the UI as you mention, then I wouldn't have a problem with it as it gives more control to theme developers.

I guess perhaps we'll want things open to developers to make those choices just like they do every day in CSS. We can limit user choices but choosing not to expose UI controls for every possible style property.

If the intention is to only add color UI controls for link:hover then we have a relationship between the theme.json API and the editor: users can override link hover colors defined theme.json via global or block styles.

Would there be any benefit over regular CSS to be able to add extra styles such as typography or whatever within a :hover block in theme.json?

I suppose I'm also wondering if we should restrict/ignore styles with the exception of color within elements.link.[':hover']

[getdave]

Thanks for your 👀 on this @ramonjd 🙇‍♂️

If this is limited to theme.json, and not available to controls via the UI as you mention, then I wouldn't have a problem with it as it gives more control to theme developers.

Agreed - it would be limited to Theme JSON. We will only expose UI for very specific elements and pseudo selectors.

If the intention is to only add color UI controls for link:hover then we have a relationship between the theme.json API and the editor: users can override link hover colors defined theme.json via global or block styles.

As I envisage it this is what I'm describing above when I say Theme JSON will be open but the UI will be limited. Did I understand you correctly?

Would there be any benefit over regular CSS to be able to add extra styles such as typography or whatever within a :hover block in theme.json?

I'm not sure I see one, other than that it would allow all styling related info in a single place instead of split between theme.json for some things and style.css for others.

If we want to restrict this we're actually going to have to write more code than if we don't want to. I'd be interested in wider opinions on this though.

I suppose I'm also wondering if we should restrict/ignore styles with the exception of color within elements.link.[':hover']

Yes this is a good question. This is for individual block styles right? These are only configurable via the UI correct? In which case we'd want to lock these down to a limited subset of values which the project deems are suitable. The criteria for this would be based on how it impacts a11y, user demand .etc. Again please correct me if I have the wrong end of the stick.

When you do, can you teach me? 😄

I'd have to charge 😜

[getdave]

👀 needed here on the regex which intends to match a pseudo selector within a selector.

[adamziel]

This won't correctly match pseudoelements like ::first-letter and mixed states such as :active:hover, but it also doesn't have to at this point. Other than that, it looks good.

[getdave]

I could see no reason that we needed this. The element selector rules seemed to be generated ok without it.

[getdave]

These changes need careful reviewing to ensure the expected selectors are accurate and the actual output is also suitable.

[adamziel]

It looks reasonable to me

[getdave]

Previously we aborted here. Now we must continue in order to ensure that pseudo selectors can be processed later on.

[ramonjd]

As I envisage it this is what I'm describing above when I say Theme JSON will be open but the UI will be limited. Did I understand you correctly?

Yes! I just wanted to make sure I had understood things correctly 😄

If we want to restrict this we're actually going to have to write more code than if we don't want to. I'd be interested in wider opinions on this though.

Good point. I'm just wondering if, by being permissive in the styles we allow inside a pseudo block, we'd cause havoc to theme authors later should we ever change or restrict them.

Maybe some theme.json elders can chime in here 😄

This is for individual block styles right? These are only configurable via the UI correct? In which case we'd want to lock these down to a limited subset of values which the project deems are suitable.

Yeah, I was thinking of anywhere where we'd set a link:hover color (global, blocks styles in the post editor) via the UI. Restricting at this level sounds like a reasonable compromise 👍

[mburridge]

Added the Needs Dev Note label in case this needs a dev note (either individual or as part of a "misc" dev note) for WP 6.1 release.

[scruffian]

I mentioned it in this post: https://make.wordpress.org/core/?p=98557&preview=true

[mburridge]

Thanks @scruffian. Might it be worth adding the #dev-notes tag to that post?

[getdave]

https://make.wordpress.org/core/?p=98557&preview=true

I can't see that post @scruffian.

[getdave]

WP 6.1 Dev note

In 6.1 support has been added to allow developers to define styles for pseudo classes (e.g. :hover, :focus) for a limited set of elements via Theme JSON.

Support for this feature is available both for root level elements and also for elements on per-block basis.

To add these styles, include the appropriate pseudo class (prepended with a semicolon) in your style definitions and then nest additional styles rules within this to define how your element should look when the pseudo class is active:

{
    "elements": {
        "link": {
            "color": {
                "text": "green"
            },
            ":hover": {
                "color": {
                    "text": "hotpink"
                }
            }
        }
    }
}

This will result in the following CSS being output in a Theme (please note actual output may vary):

a {
    color: green;
}

a:hover {
    color: hotpink;
}

This functions similarly at a block level, the only difference being the rules should be applied to the elements nested within the block you wish to target:

{
    "blocks": {
        "core/group": {
             "elements": {
                "link": {
                    ":hover": {
                        "color": {
                            "text": "red"
                        }
                    }
                }
            }
        }
    }
}

In this case <a> elements within a core/group block will have red text on :hover - this results in the following CSS (actual output may vary):

.wp-block-group a:hover {
    color: red;
}

At the current time support for this feature is intentionally limited to only link (i.e. <a>) and button elements to avoid a11y and usability concerns. It may be extended in future.