Introduce Element.json

[adamziel]

What problem does this address?

As of recently, the Site Editor supports button elements.

The idea was to have a building block that's can be managed and embedded in other blocks (such as search), but that isn't a Gutenberg block in itself and thus doesn't support features like reordering.

Here's a problem: how to surface the Button element in global styles UI?

@scruffian explored updating the relevant sidebar components in #41659, but it requires updating four files:

• packages/edit-site/src/components/global-styles/screen-typography-element.js
• packages/edit-site/src/components/global-styles/screen-typography.js
• packages/edit-site/src/components/global-styles/screen-colors.js
• packages/edit-site/src/components/global-styles/ui.js

That's a lot of files and a lot of copypasted code!

Let's go a step further – how do we manage spacings, borders, and anything else that applies? How do we attach custom CSS?

This exact problem is already solved for blocks via block.json and the "supports" config key.

What is your proposed solution?

Let's introduce an element.json file – a declarative way of introducing and configuring elements.

With element.json in place, the above PR could look as follows:

// packages/edit-site/src/elements/button.json
{
	"$schema": "https://schemas.wp.org/trunk/element.json",
	"name": "button",
	"title": "Button",
	"supports": {
		"color": {
			"__experimentalSkipSerialization": true,
			"gradients": true,
			"__experimentalDefaultControls": {
				"background": true,
				"text": true
			}
		},
		"typography": {
			"fontSize": true,
			"__experimentalFontFamily": true,
			"__experimentalDefaultControls": {
				"fontSize": true
			}
		}
	}
}

Adding support for margins and would involve adding the relevant spacing and __experimentalBorder configuration keys.

cc @scruffian @draganescu @getdave @dmsnell @mcsf @gziolo @Mamaduka @noisysocks @tellthemachines @ellatrix @ramonjd @andrewserong @mtias

[scruffian]

I think this is a good idea, but I'm not sure it should follow the same structure as block.json. Options like supports > __experimentalDefaultControls don't really make sense for elements.

[andrewserong]

Oh, interesting — yeah, the Typography controls in global styles don't currently use the Tools panel, but the Spacing controls appear to, so it might still be useful for margin/spacing?

[andrewserong]

What a fascinating idea @adamziel! I quite like the idea of defining it in an element.json file that uses much the same schema as the block.json. Would the server-side implementation ever need to look up the block.json file, too? If so, I was wondering where the file might live, and how it might be accessed (or if that's out of scope for this particular idea). Also, just CC: @aaronrobertshaw and @glendaviesnz for visibility, too.

[Mamaduka]

I'm also curious about this. Reading a lot of JSON files on every page load has its costs.

[adamziel]

Good question! I don't have a good answer because I don't even know which supports APIs would be applicable to elements at this point. It sounds like a good indicator that a new .json is quite excessive for starters. Let's see how far an elements.js file exporting a single object can take us and resume this discussion if/when we hit the wall.

[andrewserong]

Let's see how far an elements.js file exporting a single object can take us

That sounds like a good idea to me!

[draganescu]

My initial reaction here is that blocks are infinite in number and infinitely configurable, while elements are a handful with a handful of configurations. It seems a really heavy solution.

[mtias]

Sorry for the delay, but I agree. Elements is something we should keep with a very low profile because it's not as flexible and native as blocks are in terms of composition and introspection. For example, we cannot easily tell when an element might be used on a page. We can easily tell when a block is used. This means we can ensure block styles are as performant as it gets. Elements, on the other hand, can incur penalties if not used at the moment.