Stabilize Typography Block Supports Keys

[andrewserong]

Part of:

• Tracking: Addressing Design Tooling Consistency #43241 and
• Tracking: Typography Design Tools Consistency #43242

This issues tracks progress towards stabilizing the typography block support. Note that in order to provide backwards compatibility for block plugins out in the wild, fallback support for the existing __experimental prefixes should be provided.

Stabilize the following typography block supports:

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

Tasks

• Update PHP block support code in lib/block-supports/typography.php to use the non __experimental prefix, falling back to the __experimental prefix if available.
• Update the JS implementations of the typography block supports to point to the non __experimental prefix, falling back to the __experimental prefix if available.
• Update the block.json schema to support the non __experimental prefix
• Update the core blocks' block.json files to use the non __experimental prefixes
• Update the supports documentation to include the new non prefixed versions.

In my opinion, in order to provide the widest possible support for block plugins, I think it could be valuable to provide fallback support for the __experimental in the long-term. In other words, when implementing the fallback ideas above, let's do so in a way that's easy to maintain.

[carolinan]

@scruffian I am unsure of if writingMode should be stabilized without the text orientation changes? (#60030)

[scruffian]

@scruffian I am unsure of if writingMode should be stabilized without the text orientation changes? (#60030)

I agree

[andrewserong]

Oh, thanks for flagging! I'm working on a draft PR over in #63401 — I'll omit writingMode from the stabilisation for now 👍

[ndiego]

This is a fantastic initiative @andrewserong . While we are at it, can we also tackle __experimentalBorder and __experimentalDefaultControls? I am happy to open an issue for these, but didn't want to jump the gun if you were already planning on doing so. Just let me know either way.

[andrewserong]

I am happy to open an issue for these, but didn't want to jump the gun if you were already planning on doing so. Just let me know either way.

Thanks @ndiego, if you wouldn't mind opening an issue for those, that'd be great! My main focus right now is on the Typography support and this initial stage, so that we can contain the scope of the changes we're rolling out. But my hope is that with #63401 it should make subsequent stabilization a bit easier 🙂

[andrewserong]

Update: the initial PR for stabilizing the Typography supports for WP 6.8 has landed in #63401. That PR updated the JS and PHP implementations so that both the experimental and non-experimental prefixes are handled for the Typography support. Hopefully what's landed can be used as a basis for the parallel work in stabilizing other supports such as border (#64312).

I'll be heading off on sabbatical in under two weeks so I likely won't have time to contribute much more to this work. From my perspective, some next steps include (this is partly copy+pasted from the issue description):

• Rebase and land a core backport for the PHP implementation of the block support stabilization (WIP here: Stabilize experimental block supports including typography, border, and common flags wordpress-develop#7069)
• Update the block.json schema to support the non __experimental prefix
• Update the core blocks' block.json files to use the non __experimental prefixes
• For WP 6.8, update the supports documentation to include the new non prefixed versions.

FYI: @ndiego, @aaronrobertshaw, @ramonjd

[aaronrobertshaw]

Nice work progressing this stabilization effort @andrewserong 👍

I have a couple of small questions regarding the proposed task list.

Update the block.json schema to support the non __experimental prefix, with a note that it is only as of WP 6.8+

What's the plan for noting that version requirement, just in the property's description? It doesn't look like we added that information when past supports etc were added or stabilized. Do you think it's needed? Or is it conveyed via the schema as it is in the version of Gutenberg or Core in question?

Once WP 6.8 is released, update the block.json schema to remove the __experimental prefix.

My understanding was that the schema didn't document experimental properties. Quickly glancing at the schema I don't see any reference to experimental block support properties.

[andrewserong]

Good catches @aaronrobertshaw! I was copy+pasting from my previous notes, but hadn't gone back to check on the current state of the block.json schema. It looks like since July 24th there's no longer references to the WP version, so that simplifies things a bit: #63591

I'll update the task lists here to be:

• Update the block.json schema to support the non __experimental prefix

And remove the Once WP 6.8 is released item — I could have sworn we used to document some of the experimental properties but I must have been imagining things 👍

Thanks for double-checking!

[aaronrobertshaw]

It looks like since July 24th there's no longer references to the WP version, so that simplifies things a bit: #63591

My read of #63591 is that it didn't change anything with regards to the block.json schema and removing WordPress versions. I might still be missing something 🤷

I could have sworn we used to document some of the experimental properties

Is it possible you were thinking of the selectors definition in the block.json schema? That accepts selectors for all the experimental supports however it was decided then that it should use "stabilized" keys.

[andrewserong]

My read of #63591 is that it didn't change anything with regards to the block.json schema and removing WordPress versions. I might still be missing something 🤷

No, I don't think it really changed anything in that respect, but it changed my perspective on it 🙂. It removed a reference to **Note:** Since WordPress 6.1. — when I wrote this issue seeing that was what gave me the idea that we could add some Since text for when these newly stabilized attributes were added. Looking at it today, though, I don't think the block.json schema is the right place for it. Whereas in the block-supports.md file we do have the "since" descriptor, e.g. here:

gutenberg/docs/reference-guides/block-api/block-supports.md

Line 1072 in 1f876be

_**Note:** Since WordPress 6.6._

So for consistency it looks like flagging the version in which something is introduced is best done in that doc rather than in schemas. 🤔

But do feel free to make any changes to the approach here! In the end it might not be necessary to flag which version a block support was introduced in, as it might be clear enough from Dev Notes. My main (weakly held) thought was that it could be useful for folks building custom block plugins to be able to see easily enough when a block support was introduced so that they know which Requires at least to flag their plugin as.

[aaronrobertshaw]

It looks like stabilization of experimental block supports will be punted for 6.8. See #68163 and #67729 (comment) for context.

[ramonjd]

The work that's gone into this so far has been reverted in:

• Block Supports: Revert stabilization of typography, border, skip serialization and default controls supports #68163

Thanks to everyone who helped move it forward, and tease out lessons for when folks return to it.

See background context: #67729 (comment)