Style engine: rename at_rule to rules_groups and update test/docs

[ramonjd]

What?

A minimal change that builds on:

• Add style engine support for nested at-rules. #58867

by:

1. renaming $at_rule to $rules_group.
2. Adds missing tests
3. Updates docs

Props to @tellthemachines and @andrewserong

Why?

To make it clear that it supports other styles nesting patterns. For example, "rules group" could be a nesting style rule, a conditional group rule or at-rule groups.

Increase test coverage.

Future possibilities, including supporting merging rules groups and @keyframes outlined in #58918

Testing Instructions

npm run test:unit:php:base -- --group style-engine

[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: ramonjd <ramonopoly@git.wordpress.org>
Co-authored-by: andrewserong <andrewserong@git.wordpress.org>
Co-authored-by: tellthemachines <isabel_brison@git.wordpress.org>

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

[github-actions]

This pull request has changed or added PHP files. Please confirm whether these changes need to be synced to WordPress Core, and therefore featured in the next release of WordPress.

If so, it is recommended to create a new Trac ticket and submit a pull request to the WordPress Core Github repository soon after this pull request is merged.

If you're unsure, you can always ask for help in the #core-editor channel in WordPress Slack.

Thank you! ❤️

View changed files

❔ phpunit/style-engine/class-wp-style-engine-css-rule-test.php
❔ phpunit/style-engine/class-wp-style-engine-css-rules-store-test.php
❔ phpunit/style-engine/class-wp-style-engine-processor-test.php
❔ phpunit/style-engine/style-engine-test.php

[andrewserong]

Thanks for the follow-up @ramonjd, I like the idea of going with rules_group as a wider catch-all to encompass both at rules as well as other groups further down the track 👍

Just left a few nits on the tests and a comment on a doc comment and about nullish coalescing, but nothing major. Might be worth double-checking with @tellthemachines on the naming, too, given this builds on #58867, but this LGTM! ✨

[ramonjd]

Just left a few nits on the tests and a comment on a doc comment and about nullish coalescing, but nothing major. Might be worth double-checking with @tellthemachines on the naming, too, given this builds on #58867, but this LGTM! ✨

Thanks for testing! I've added your suggestions. I'll hold off merging until @tellthemachines gets time to check it out.

Cheers!

[tellthemachines]

Thanks for the additional tests!

My only reservation is rules_group is a bit misleading as it seems to indicate that its intent is to group rules under the selector or at-rule we pass to it. I understand wanting to not limit the possibilities, but realistically the only possibility here that's not an at-rule is native CSS nesting, which is a feature primarily geared towards static stylesheet maintainability. There's no real benefit in using it for dynamically generated CSS, so my cautious prediction (not wanting to start a polemic here, in case this is something folks feel strongly about 😅) is that it's unlikely to ever be needed in core.

That said I'm not super fussed either way, so feel free to merge this! I don't have any better generic naming idea. As long as the docs make clear what can and can't be done, we should be fine.

[tellthemachines]

Missed opportunity to use color:tomato here 😄

[ramonjd]

Mind blown. I'm updating this later 🤣

[ramonjd]

Thanks for the reviews, folks!

[ramonjd]

As long as the docs make clear what can and can't be done, we should be fine.

I'll do a follow up on the docs and also at tomato 😄

My only reservation is rules_group is a bit misleading as it seems to indicate that its intent is to group rules under the selector or at-rule we pass to it. I understand wanting to not limit the possibilities, but realistically the only possibility here that's not an at-rule is native CSS nesting

You're right. I suppose I was thinking more of the behaviour of the property (it will always nest), not the property itself.

I recognize the problem is that I'm overthinking/agonizing too much over little things 😄 I'll stop now.

Ultimately folks will use this API how they wish despite how things are named, e.g., 'selector', which could also be an at-rule. 😄

I know I already merged this, but I'm not in love with any particular way so I'm happy to follow up with any changes before the next WordPress release.

By the way, I also tried out nesting one level of rules too in the arguments passed to wp_style_engine_get_stylesheet_from_css_rules

				array(
					'selector' => ' > 'some_string',
					'rules'    => array(
						'rules' => array(
                                                          'selector' => ' > 'some_string',
                                                   )
					),
				),

Was a bit "nesty" though 😄