Allow the style property of block.json to be an array and add support for object-based block styles

[adamziel]

What problem does this PR solve?

In WordPress/gutenberg#34180 we moved block CSS to blockJson.supports.__experimentalStyle. This PR moves it under blockJson.style at the root level. The goal is to only have a single location where styles are defined.

Block.json before this PR:

{"supports": {"__experimentalStyle": {"border": {"color": {"text": "#fff","background": "#32373c"}}}},"style": "wp-block-button"}

Block.json after this PR:

{"style": ["wp-block-button",{"border": {"color": {"text": "#fff","background": "#32373c"}}}]}

This PR is an alternative to WordPress/gutenberg#41656

Other considerations

This is a breaking change – any existing code that assumes style to be a single item or an array of strings will throw a notice at best.

Test plan

1. Apply this PR to your local wordpress-develop
2. Run npm run build
3. Apply Move block css from supports > __experimentalStyle to a top level style key in block.json gutenberg#41873 to your local Gutenberg installation
4. Build Gutenberg
5. Switch themes to TwentyTwentyTwo
6. Create a new page
7. Insert a button, give it some text
8. Save it, view it on the frontend
9. Confirm the buttons have a large padding at the bottom

cc @getdave@scruffian@draganescu

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

[scruffian]

This is a breaking change – any existing code that assumes style to be a single item or an array of strings will throw a notice at best.

This seems like a blocker. Can we change it to allow for strings as well?

[adamziel]

This seems like a blocker. Can we change it to allow for strings as well?

@scruffian oh it can be a string. I'm saying it can be either of:

• A string
• An array of strings
• A mixed array of strings and arrays

Therefore, any code that assumes it's just a string or string[] will break.

[adamziel]

@scruffian I applied all the feedback and refreshed the related Gutenberg PR. This one is ready for another review!

[gziolo]

@adamziel, thank you so much for looking into adding native support for multiple style styles per block type. It's all going in the right direction. It will require a bit more work to propagate changes to other places:

• WP_Block_Type class:
  

  wordpress-develop/src/wp-includes/class-wp-block-type.php

  Lines 199 to 205 in a5b555a

  	/**
  	* Block type front end and editor style handle.
  	*
  	* @since 5.0.0
  	* @var string|null
  	*/
  	public$style = null;

• WP_REST_Block_Types_Controller class:
  

  wordpress-develop/src/wp-includes/rest-api/endpoints/class-wp-rest-block-types-controller.php

  Lines 544 to 550 in a5b555a

  	'style' => array(
  	'description' => __( 'Public facing and editor style handle.' ),
  	'type' => array( 'string', 'null' ),
  	'default' => null,
  	'context' => array( 'embed', 'view', 'edit' ),
  	'readonly' => true,
  	),

This will include also existing unit tests for both classes. New functionality requires also unit test coverage.

I don't think we consume style from the REST API endpoint in Gutenberg, but we should double-check to be on the safe side.

We should also extend the existing documentation for block.json to include the newly supported format of styles:
https://github.com/WordPress/gutenberg/blob/trunk/docs/reference-guides/block-api/block-metadata.md#style

What is the reason this patch covers only style but not editorStyle?

[gziolo]

We will have to put an empty _wp_multiple_block_styles function with the deprecation message, example:

wordpress-develop/src/wp-includes/deprecated.php

Lines 4305 to 4313 in 0abc2b2

	/**
	* Inject the block editor assets that need to be loaded into the editor's iframe as an inline script.
	*
	* @since 5.8.0
	* @deprecated 6.0.0
	*/
	functionwp_add_iframed_editor_assets_html() {
	_deprecated_function( __FUNCTION__, '6.0.0' );
	}

[gziolo]

It looks like we have everything covered so it needs a final review and a round of testing with and without the Gutenberg plugin.

[adamziel]

I think we're good now! GitHub CI seems to be down, though, so might be worth waiting until it's up again before merging.

[adamziel]

All the tests passed! Would you please help get this PR approved? CC @gziolo@aristath@scruffian@getdave

[scruffian]

LGTM

[adamziel]

@gziolo do you think you could merge this one?

[adamziel]

cc @mtias for soundness check – does this change seem reasonable to you?

[gziolo]

The example shared in the description looks nice in my opinion as it consolidates several available options. In the future, we could also use the same API borrowed from theme.json for style variations:

{
"styles": [
{
"name": "default",
"label": "Default",
"isDefault": true
},
{
"name": "other",
"label": "Other",
"settings": {
"border": { "color": {
"text": "#000",
"background": "#ccccc"
}
}
}
}
],
"style": [ "wp-block-button", {
"border": { "color": {
"text": "#fff",
"background": "#32373c"
}
}
} ]
}

[gziolo]

Let's land WordPress/gutenberg#41873 in the Gutenberg plugin first and give it a try before we include it in WordPress core. Code-wise everything is ready, and it had enough reviewers. We mostly need to validate that the extended API for style in block.json is friendly for developers – it's mostly the question of whether it's intuitive and straightforward to document.

[adamziel]

I'm closing this in favor of #3108