Stabilize experimental block supports including typography, border, and common flags

[andrewserong]

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

This PR brings the changes from the following Gutenberg PRs to core:

• Typography: Stabilize typography block supports within block processing gutenberg#63401
• Borders: Stabilize border block supports within block processing gutenberg#66918
• Block Supports: Extend stabilization to common experimental block support flags gutenberg#67018

Note: The approach here is slightly different to in Gutenberg which relies on filters. Here, the transformations that map experimental to stable keys are handled within the WP_Block_Type class to avoid reliance on filters.

The proposal here is to stabilize the __experimental form of block support keys when props are set on a block type instance. This occurs during registration or when a WP_Block_Type object is instantiated. There was some discussion in an earlier Gutenberg PR about potentially performing this transformation in the block registry instead — however I couldn't find a good precedent for it, and it seems slightly more encapsulated to me to keep the transformation close to where the supports key is stored.

I'm very happy for feedback on this, though!

What's being stabilized?

Experimental block supports stabilized include:

• Border support: __experimentalBorder → border

Experimental block support features stabilized include:

• __experimentalFontFamily → fontFamily
• __experimentalTextDecoration → textDecoration
• __experimentalFontStyle → fontStyle
• __experimentalFontWeight → fontWeight
• __experimentalLetterSpacing → letterSpacing
• __experimentalTextTransform → textTransform

Shared or common experimental block support flags stabilized include:

• __experimentalSkipSerialization → skipSerialization
• __experimentalDefaultControls → defaultControls

Test Instructions

Editor

JS package updates will be required for the editor to function with the stabilized block supports.

The editor's block supports use JS hooks to function and without the package updates will still be checking the old experimental block support keys. After applying the block support stabilization in the core block type class, the experimental keys won't exist, so the UI will not correctly reflect the stable config.

Frontend

To test the PHP side of block support stabilization:

1. On trunk:
   • add several blocks of different types with different block supports to a post
   • ensure some of the included blocks skip serialization, such as an Image block with borders
   • apply some custom global styles for the blocks added above
   • select individual blocks and apply block support styles for those block instances
   • save the post and view it in a separate tab to reference later
2. Check out this PR branch
   • confirm the block supports and theme.json resolver unit tests are passing
   • in a new tab, view the earlier post on the frontend
   • make sure all the global styles and block instance styles are still applied correctly

---

This Pull Request is for code review only. Please keep all other discussion in the Trac ticket. Do not merge this Pull Request. See GitHub Pull Requests for Code Review in the Core Handbook for more details.

[andrewserong]

This code intentionally does not unset the experimental version of the supports. This is so that the un-updated JS code in the editor can handle the experimental syntax, and (for now at least) feels slightly safer in terms of backwards compatibility.

[github-actions]

Test using WordPress Playground

The changes in this pull request can previewed and tested using a WordPress Playground instance.

WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Some things to be aware of

• The Plugin and Theme Directories cannot be accessed within Playground.
• All changes will be lost when closing a tab with a Playground instance.
• All changes will be lost when refreshing the page.
• A fresh instance is created each time the link below is clicked.
• Every time this pull request is updated, a new ZIP file containing all changes is created. If changes are not reflected in the Playground instance,
  it's possible that the most recent build failed, or has not completed. Check the list of workflow runs to be sure.

For more details about these limitations and more, check out the Limitations page in the WordPress Playground documentation.

Test this pull request with WordPress Playground.

[andrewserong]

Based on discussion over in WordPress/gutenberg#63401 (comment), I've updated this to move the stabilization to after the filter is run. This ensures that any opt-outs, etc, performed by plugins are appropriately stabilized before the props are set.

I've also moved the logic into a private method so that set_props is easier to read.

[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.

Core Committers: Use this line as a base for the props when committing in SVN:

Props aaronrobertshaw, andrewserong, ramonopoly.

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

[aaronrobertshaw]

The latest plan is to backport all the block support stabilization updates in a single PR. This will include stabilizing border block supports and shared experimental flags such as __experimentalDefaultControls and __experimentalSkipSerialization.

More details can be found in WordPress/gutenberg#66918 (comment).

In the near future, I'll pick up this backport and update it accordingly, while @andrewserong is away.

[aaronrobertshaw]

I've pushed some updates to this PR bringing in the broader stabilization of other block supports e.g. __experimentalBorder, __experimentalSkipSerialization etc.

The trac ticket and PR description have been updated with the latest info.

[ramonjd]

So far I've tested this PR against WordPress/gutenberg#63401 (Typography)

✅ Typography controls work as expected with and without __experimental*
✅ Everything renders correctly in the site editor and frontend
✅ Disabling supports, e.g., __experimentalFontFamily disables controls in the UI

Actually, I made a mistake here. I had the plugin installed. 🤦🏻

I'm not sure what I should be seeing in the editor. I understand the packages eventually need to be updated, but I expected no regressions in the UI.

Here's what I'm seeing for paragraph blocks

Trunk	This PR

How have you been testing this @aaronrobertshaw ?

[ramonjd]

Same for border supports.

Here's what I'm seeing for the group block:

Trunk	This PR

Am I doing something wrong? I would have assumed, even without the package update, that the controls work with the current __experimental flags.

[aaronrobertshaw]

Thanks for testing @ramonjd and apologies for the confusion. I should have updated the test instructions on this PR further.

I'm not sure what I should be seeing in the editor. I understand the packages eventually need to be updated, but I expected no regressions in the UI.

The TL;DR is we need the JS package updates.

I've added the longer version to the PR test instructions but the PHP changes here stabilize the block supports in the block type. My understanding is the stabilized block type data is passed to the editor but the JS block support hooks etc will still be checking the __experimental prefixed block support keys. They don't exist after stabilization hence the "missing" UI elements as the editor believes the blocks don't have support.

How have you been testing this @aaronrobertshaw ?

I'd primarily tested using the unit tests and by creating blocks with global and block support styles applied on trunk, then switching to this branch and checking they were still applied correctly on the frontend. I'm definitely open to better testing approaches but my brain broke trying to come up with one.

The PR test instructions have been updated to something more useful. I'll re-test it all myself tomorrow as I'm out of time this evening.

[ramonjd]

I'm not sure but I think the is_array( $config ) check from this Gutenberg PR is missing.

So testing using the steps in WordPress/gutenberg#66918, when I set the entire support config to a bool, e.g., settings.__experimentalBorder = false using a filter I get the PHP error:

Fatal error: Uncaught TypeError: array_merge(): Argument #2 must be of type array, bool given in /var/www/html/wp-includes/class-wp-block-type.php:774

Presumably because $stable_config is a bool (false).

Suggested change

	if ( is_array( $supports[ $stable_support_key ] ) ) {
	if ( is_array( $supports[ $stable_support_key ] ) && is_array( $stable_config ) ) {

[aaronrobertshaw]

Thanks for flagging this, I'll investigate it.

The border support stabilization's approach and code was changed by the final PR stabilizing the common experimental flags. There's a good chance that last PR introduced this bug to Gutenberg as well. I'll need to looking into both.

[aaronrobertshaw]

At a quick glance, this backport does reflect the Gutenberg code in its current state. Both will need to be updated to handle a scenario where one of the top-level keys (experimental or stable) is a boolean.

I'll update this shortly and spin up a quick PR to fix Gutenberg.

[aaronrobertshaw]

A quick PR for the Gutenberg side of this is up in WordPress/gutenberg#67552.

[aaronrobertshaw]

I've brought across the fix from WordPress/gutenberg#67552 in ef6959b. I'm out of time today but will give it more of a test tomorrow.

[ramonjd]

To test I used the Gutenberg plugin, but disabled the gutenberg_stabilize_experimental_block_supports hook and prevented Gutenberg from registering typography and border block supports.

So far, with the exception of border, the support and common flags appear stable and work as expected.

I'll do another test tomorrow.

[ramonjd]

Thanks for pulling across WordPress/gutenberg#67552!!

This is testing well for me in all scenarios so far.

✅ typgography.__experimental* and their stable counterparts work as expected
✅ __experimentalBorder and border the same
✅ blocks with skipSerialization e.g., image, appear as expected
✅ changes to __experimentalDefaultControls and defaultControls have effect in the UI

[aaronrobertshaw]

Quick update:

There's an alternate approach being explored as part of WordPress/gutenberg#67729. I'll hold off on committing this PR until that plays out.