Add section styling via extended block style variations

[aaronrobertshaw]

Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This will amplify the site-building potential of pattern overrides, zoomed out mode etc.

A full history of the feature can be found in: ​https://github.com/WordPress/gutenberg/issues/57537

The following Gutenberg PR needs to be synced to core:
​https://github.com/WordPress/gutenberg/pull/57908

Provide users with the ability to style entire sections of a page without having to tediously reapply the same sets of styles. This will amplify the site-building potential of pattern overrides, zoomed out mode etc.

A full history of the feature can be found in: ​https://github.com/WordPress/gutenberg/issues/57537

Syncs the changes from: ​https://github.com/WordPress/gutenberg/pull/57908

Detailed test instructions can be found on the linked Gutenberg PR.

Trac ticket: https://core.trac.wordpress.org/ticket/61312

FYI this backport has been updated to include a bug fix which landed in Gutenberg via ​https://github.com/WordPress/gutenberg/pull/62125.

Hello! Happy Friday.

Testing first, and then I’ll look at the code.

I followed the testing steps in ​https://github.com/WordPress/gutenberg/pull/57908 basically to the letter. Thanks for writing them!

I am testing this branch and have the Gutenberg plugin disabled. It’s literally my first time looking at this feature so if I’m doing something wrong just tell me.

When I put this into my functions.php:

register_block_style(
	array( 'core/group', 'core/columns' ),
	array(
		'name'       => 'green',
		'label'      => __( 'Green', 'twentytwentythree' ),
		'style_data' => array(
			'color'    => array(
				'background' => '#4f6f52',
				'text'       => '#d2e3c8',
			),
			'blocks'   => array(
				'core/group' => array(
					'color' => array(
						'background' => '#739072',
						'text'       => '#e3eedd',
					),
				),
			),
			'elements' => array(
				'link' => array(
					'color'  => array(
						'text' => '#ead196',
					),
					':hover' => array(
						'color' => array(
							'text' => '#ebd9b4',
						),
					),
				),
			),
		),
	)
);

I received this notice:

Notice: Function WP_Block_Styles_Registry::register was called incorrectly. Block name must be a string.

I worked around this by replacing the array(...) with just ’core/group'.

I noticed that, with that code above, links within a Group block on the frontend correctly received a #ead196 colour but links within a Group block in the editor remained black. It’s a similar story for the #739072 background on nested Group blocks. I could see that in the frontend but not the editor.

I’m not sure what this means:

Double check whether block style variations with margin styles work correctly when alongside layout global styles.

Do you have an example to test?

When I added a variation by creating a styles/variation-a.json file or by setting styles.blocks.variations in theme.json, I saw that Variation A came up as an option for Group and Columns blocks but selecting that variation didn’t change any of the block’s colours.

Thanks for testing @noisysocks and @ramonjd 👍

I received this notice:

Sorry, it looks like I missed rebasing this PR after the backport for extending block style registration. I'll get it updated shortly.

I’m not sure what this means:

Double check whether block style variations with margin styles work correctly when alongside layout global styles.

By that it meant, if a block style variation specifies margin styles, they don't incorrectly override margin styles set by layout styles e.g. the left/right margins on top level blocks etc. Once I sort out the other feedback, I'll circle back and try and come up with a concrete example.

Sorry, it looks like I missed rebasing this PR after the backport for extending block style registration.

Was just coming here to ask for a rebase 😄

Ok, this has been rebased and the indentation sorted. Well I hope the indentation/linting issues are sorted, I don't trust my local phpcs/phpcbf config right now 😅

I've been testing this mainly by registering style variations in PHP, both with classic and block themes, and it's working as expected for both ✅
Also checked that existing style variations, whether core or theme-declared, are still working correctly ✅

I noticed that, with that code above, links within a Group block on the frontend correctly received a #ead196 colour but links within a Group block in the editor remained black. It’s a similar story for the #739072 background on nested Group blocks. I could see that in the frontend but not the editor.

Apologies @noisysocks, I messed up the test instructions. The editor side of this feature requires the JS changes in Gutenberg to function properly there.

I'll update the instructions for others that might be testing this one.

Got it, that makes sense. It think the only issue I'm seeing now then is this one:

When I added a variation by creating a styles/variation-a.json file or by setting styles.blocks.variations in theme.json, I saw that Variation A came up as an option for Group and Columns blocks but selecting that variation didn’t change any of the block’s colours.

Here's a video:

​https://github.com/WordPress/wordpress-develop/assets/612155/187ca985-c7fc-45c7-8e9a-8d00b23ce002

Appreciate the continued patience here @noisysocks 🙇

The catch with the variation partial used there is that it references css custom properties not present in TwentyTwentyFour. Switching those up to simple hex values might be the best bet for testing.

I'll go and update the original PR's snippets so they don't catch anyone else out.

I'm running through the scenarios from the Gutenberg PR ​https://github.com/WordPress/gutenberg/pull/57908

So far:

✅ blockTypes blocks are being registered correctly and styles applied on frontend (tested using using theme.json and register_block_style)

✅ existing block style variations on core blocks continue to work

✅ Applying a variation within a block that already has a variation has the correct styles applied

✅ Setting element styles on an individual block instance continues to take precedence

Just finished a round of specificity testing, e.g., Top-level, blocks, elements and CSS is being applied as I'd expect.

LGTM!

The catch with the variation partial used there is that it references css custom properties not present in TwentyTwentyFour. Switching those up to simple hex values might be the best bet for testing.

I'll go and update the original PR's snippets so they don't catch anyone else out.

Makes sense 👍 thanks!

I changed the var()s in my test code to be hex colours and it works well now.

[noisysocks]

In 58264:

Block Themes: Add section styling via extended block style variations

Provide users with the ability to style entire sections of a page without
having to tediously reapply the same sets of styles.

This is done by extending block style variations to apply to nested blocks.

See ​https://github.com/WordPress/gutenberg/pull/57908.

Fixes #61312.
Props aaronrobertshaw, talldanwp, ramonopoly, isabel_brison, andrewserong.

Committed in r58264.

@noisysocks ☝️

[noisysocks]

In 58265:

Fix indentation and whitespace in WP_Theme_JSON and WP_Theme_JSON_Resolver

Props mukesh27.
Follows r58264.
See #61312.

Thanks @mukeshpanchal27, addressed in r58265. Are you interested in fixing phpcs so that it automatically catches this kind of stuff? 😀

Trac ticket: https://core.trac.wordpress.org/ticket/61312

Fixes: ​https://github.com/WordPress/gutenberg/issues/62303
Alternative to ​https://github.com/WordPress/gutenberg/pull/62405#issuecomment-2155131064

## What?

This PR changes how the block style variations defined by the theme are registered: from using the wp_theme_json_data_* filters to use the init filter.

## Why?

Using the wp_theme_json_data_* filters is problematic: in some scenarios (e.g.: ) variations end up not being registered because those filters were not dispatched, hence their styles are not generated. Using init is in line with what themes have been doing until now in their functions.php and makes sure the style variations are registered in all the places.

## How?

• b5e5f4d853cc640d78ccbdafe866c3302bb6edf4 Hook into the init hook and register the block style variations from the 3 places where they can come from:
  • theme.json "partials": json files stored in styles/ that are not theme style variations
  • theme's theme.json
  • user's theme.json (this would come from the theme style variations defined by the theme)
• 85e3c2f2e95f570a33dad0f950b2b451f8022f66 Remove the code that registers them upon dispatching the wp_theme_json_data_* filters.

## Testing Instructions

1. Register style variations in all the places the theme is allowed to (use TT4).

In the theme.json file of the theme, paste the following under styles.blocks.variations:

"ThemeDark": {
    "blockTypes": [
        "core/group",
        "core/columns"
    ],
    "color": {
            "background": "blue"
    }
}

In the styles/ember.json (theme style variation) file, paste the following under styles.blocks.variations:

"VariationDark": {
    "blockTypes": [
        "core/group",
        "core/columns"
    ],
    "color": {
            "background": "yellow"
    }
}

Create a new file called styles/partial.json (partial theme.json), and paste the following:

{
        "$schema": "https://schemas.wp.org/trunk/theme.json",
        "version": 2,
        "title": "PartialDark",
        "blockTypes": [ "core/group", "core/columns", "core/media-text" ],
        "styles": {
                "color": {
                        "background": "green"
                }
        }
}

2. Open the site editor, go to Styles, apply the "Ember" theme style variation and save.
3. Go to the site editor, select a group block, and verify the three new style variations are available:

4. Edit the styles of one of them, for example, PartialDark. Go to "Global Styles > Blocks > Group > PartialDark". Modify the background color to something else.
5. Save the post. The expected result is that it stays as it is (it's not reset to the default).

​https://github.com/WordPress/wordpress-develop/assets/583546/14bf5644-4203-4921-87c3-10a282632a5a

There's a legit error on the WP_Block_Supports_Block_Style_Variations_Test::test_add_registered_block_styles_to_theme_data test. I ran out of time today to look at this but will take a look tomorrow.

There's a legit error on the WP_Block_Supports_Block_Style_Variations_Test::test_add_registered_block_styles_to_theme_data test

This test retrieves the theme origin data via the resolver. So the registration of styles was happening via the wp_theme_json_data_theme prior to this PR's switch to the init action.

If we either call do_action('init') or wp_register_block_style_variations_from_theme() within the test after the theme switch, it passes successfully again.

It might also be worth tweaking the name of wp_register_block_style_variations_from_theme to reflect its from theme json rather than generically from a theme.

I've created a corresponding PR for Gutenberg: ​https://github.com/WordPress/gutenberg/pull/62461

In testing we uncover one issue when the style variation is modified but not saved:

1. Register style variations the styles/ember.json (theme style variation) file, paste the following under styles.blocks.variations:

"VariationDark": {
    "blockTypes": [
        "core/group",
        "core/columns"
    ],
    "color": {
            "background": "yellow"
    }
}

2. Open the site editor, go to Styles, apply the "Ember" theme style variation AND DO NOT SAVE IT YET. This is the key to the issue.
3. Go to the site editor, select a group block, and verify the VariationDark is available:

4. Update the VariationDark variation by going to "Global Styles > Blocks > Group > VariationDark". Modify the background color to something else.
5. Save the post. The expected result is that the new background stays as it is and it's not reset. However, it's reset and the new color will only be available when reloading the site editor.

I've created a Gutenberg PR for the most recent updates here: ​https://github.com/WordPress/gutenberg/pull/62495

[oandregal]

In 58394:

Editor: register block style variations defined by the theme using the init action.

Props oandregal, aaronrobertshaw, annezazu.

Follow-up to [58264].
See #61312.

Committed at https://core.trac.wordpress.org/changeset/58394

[swissspidy]

Looks like this causes some issues with PHPUnit tests in plugins/themes and also the WP-CLI tests. Example: ​https://github.com/wp-cli/wp-cli/actions/runs/9543036240/job/26298897213?pr=5958

This logic causes a database query very early on, even when WP is not installed yet.

The backtrace is essentially this:

do_action('init') -> wp_register_block_style_variations_from_theme -> WP_Theme_JSON_Resolver::get_user_data -> WP_Theme_JSON_Resolver::get_user_data_from_wp_global_styles -> WP_Query

Why is this query done on init on every page load? Can this lazy loaded instead and only in the relevant areas?

[oandregal]

Why is this query done on init on every page load? Can this lazy loaded instead and only in the relevant areas?

In ​https://github.com/WordPress/wordpress-develop/pull/6844 I shared more context about this:

Initially, this feature worked by registering the block style variations using the wp_theme_json_data_* filters, see https://core.trac.wordpress.org/changeset/58264. This approach proved problematic for this flow: the user updates the styles of any of them via the global styles sidebar.

This feature was updated to use the init hook at https://core.trac.wordpress.org/changeset/58394 The rationale was that this hook is what themes currently do to register the block styles variations via the functions.php (example from TwentyTwentyFour: ​https://github.com/WordPress/wordpress-develop/blob/99bc097e5eb1d751b472b1f6da97548ec3b067c2/src/wp-content/themes/twentytwentyfour/functions.php#L147). This approach raised issues: the init hook is called during installation, hence the database is not set up — which this feature requires, as it retrieves the existing global styles for user data.

The approach in this PR is similar to how it initially worked, but with a couple of tweaks:

• It doesn't use the wp_theme_json_data_* filters. Instead, this registers the variations directly in the WP_Theme_JSON_Resolver, saving the extra processing required by the filters.
• It also registers the block style variations in the global styles endpoint, so user updates are reflected immediately in the UI without requiring a page reload.

[joemcgill]

@swissspidy and @oandregal it looks like tracking the performance of this feature is already happening in #61451. Would you two be opposed to close this and keeping all of the related discussion about performance improvements over there, or is there a reason to keep both?

[swissspidy]

I mainly reopened this ticket because this change introduced a bug with the install that needs to be fixed, not because of performance. So 2 separate things.

[joemcgill]

Thanks @swissspidy. Even though they are closely related, that makes sense to me. Let's try to keep the performance conversation on the other ticket and close this once the DB query causing the error is avoided.

[oandregal]

In 58429:

Do not use init to register block style variations defined via theme.json.

Props oandregal, aaronrobertshaw, joemcgill, ramonopoly, andrewserong, swissspidy.
See #61451.
Fixes #61312.

[oandregal]

In 58466:

Section styles: improve performance and conceptual consistency.

These changes involve:

• Move shared variation definitions from styles.blocks.variations to styles.variations
• Remove blockTypes from styles.variations.
• Do not register shared variations from theme style variation or primary theme.json files.
• Move the merging of theme.json data into the WP_Theme_JSON_Resolver and WP_Theme_JSON classes.

These changes improve performance and are more future-proof API wise.
See conversation at ​https://github.com/WordPress/gutenberg/issues/62686

Props aaronrobertshaw, oandregal, andrewserong, joemcgill, talldanwp, andrewserong, ramonopoly, richtabor, youknowriad.

See #61312, #61451.