Custom controls, block supports, and theme.json

[oandregal]

The current global styles engine works this way: if a block has declared support for a property via the block supports mechanism, that property can be used in theme.json

For example, the paragraph block declares support for some properties via block.json: text & background color, link color, font size, and line height. It looks like this:

"supports": {
  "color": {
    "link": true
  },
  "fontSize": true,
  "lineHeight": true,
},

Hence, in the theme.json those styles can be used:

"core/paragraph": {
  "color": {
    "text": "value",
	"background": "value",
	"link": "value"
  },
  "typography": {
  	"fontSize": "value",
	"lineHeight": "value"
  }
}

However, note that the paragraph doesn't support gradients, padding, or font family. If a theme.json file contains this data:

"core/paragraph": {
  "color": {
    "text": "value",
	"background": "value",
	"link": "value",
	"gradients": "value" // UNSUPPORTED PROPERTY
  },
  "typography": {
    "fontFamily": "value", // UNSUPPORTED PROPERTY
  	"fontSize": "value",
	"lineHeight": "value"
  },
  "spacing": {
  	"padding": { // UNSUPPORTED PROPERTY
		"top": "value",
		"left": "value",
		"bottom": "value",
		"right": "value"
	}
  }
}

the unsupported properties will be ignored and not converted to the corresponding CSS style.

We maintain this metadata in the server and the client.

Why it works this way & current struggles?

The rationale for this has been that is only when a block opts-in into the use of a CSS property that a theme can be sure that styles set via theme.json work as expected everywhere (locally & globally).

Additionally, we also use block.json support data to generate the UI controls for the Global Styles sidebar (no custom controls can be added here yet, these controls modify a stylesheet external to the post_content) and the block sidebar (blocks can create their own custom controls in the edit function, these modify the post_content being edited).

This approach has constraints. By asking blocks to use the block supports mechanism so they can be styled via theme.json we've experienced two issues so far:

1. We've needed to add support in theme.json for properties that don't have UI yet Add support for border configuration via theme.json #28049

2. Properties/blocks that have custom UI controls aren't supported in the theme.json. With Next iteration of block supports mechanism #28913 we're alleviating the issue by making the existing UI controls we create automatically work in more situations. However, there may be cases in which the block wants a very specific UI control and we don't have a way to register them in the global styles sidebar. There's the issue of how custom controls fit into the sidebar reorganization as well Sidebar Controls & Component System #27331

What do we need to decide?

One point is whether we want to keep the block.json <=> theme.json connection. If we disconnect them, all registered blocks will be able to use all the existing style properties in theme.json. A potential drawback is that there's no guarantee that using a particular style property in theme.json is going to work: the block can have a complex markup, there may be specificity issues, etc.

A related point is whether (and how) to support custom controls in global styles.

• If we disconnect block.json <=> theme.json this issue becomes more pressing. We have to decide what controls we present to the user in the block sidebar & global styles sidebar.
• If we don't disconnect them, we still have to decide whether or not -and how- we support custom controls in the global styles sidebar.

Related topics:

• Sidebar Controls & Component System #27331 organize sidebars
• Updates to experimental-theme.json #28163 control UI visibility via theme.json

[oandregal]

I ran this by some folks and the current views are that theme authors should be able to use any styles in theme.json independently from the block.json support. The block supports will still be used to show the UI controls in the block & global styles sidebar, in addition to theme.json configs that should take precedence.

The immediate action step for this issue is to decouple theme.json styles <=> block.json. The custom controls for global styles sidebar can be addressed later and I've added a note in the backlog at #20331

[oandregal]

Have a PR that address this at #29941

[oandregal]

This was closed by #29941