Allow plugins to include a theme.json file in the same way themes do

[Aljullu]

Description

Currently, if a plugin wants to set default styles for its blocks, it can either write the styles in CSS or write them in the block default attributes.

None of these approaches allow themes to easily override the styles of the plugin using theme.json.

A solution would be to allow plugins to include a theme.json file in the same way themes are already doing it. Styles specified in the theme.json of a plugin, would have lower priority than the styles from the theme's theme.json and user styles.

This way, plugins can specify the default styles of their blocks in their theme.json and themes can override the styles from their theme.json.

Step-by-step reproduction instructions

Screenshots, screen recording, code snippet

No response

Environment info

No response

Please confirm that you have searched existing issues in the repo.

Yes

Please confirm that you have tested with all plugins deactivated except Gutenberg.

Yes

[nerrad]

Another example of how this will be useful (for a plugin like WooCommerce) is that the plugin provided theme.json could also provide an index of the blocks (and patterns) registered in the plugin.

I would suggest however that the hierarchy of properties be something like:

User > Block > Theme theme.json > Plugin theme.json

Potential implementation options

It looks like we would need to add some theme.json detection for plugins as a part of the WP_Theme_JSON_Resolver::get_merged_data function. There's a few routes (to kick start discussion) that could be taken here in terms of how the theme.json in a plugin would be discovered:

1. Filter for plugin to register theme.json path

The filter would likely be within the get_merged_data function.

2. Path defined via property in the plugin header

Similar to how other plugin details are set in the plugin header, there could be potentially a theme.json property where the relative path could be set for the theme.json (or even a flag that just indicates the plugin has one defined?).

One advantage of having this in the plugin header is that that is already parsed by WP so it could be an aid to discoverability (only hitting the filesystem for the file if needed). There's also some potential benefits for surfacing this more readily via the WP.org plugin listing (or other automations) as well.

3. Automatic discovery via specific location for file

Having a requirement that the theme.json for a plugin is at a specific path (eg. in the plugin root folder or theme/theme.json). During activation/update WordPress would automatically check to see if plugins have a theme.json and set the plugin slug to a registry for later reading/caching when WP_Theme_JSON_Resolver::get_merged_data is invoked.

---

Personally, I'm leaning more towards options 2 and 3 (perhaps a combination of both) because it still provides an opt-in path for plugins yet keeps implementation details handled by WordPress.

[mtias]

I think the plugin should come before the theme as a fallback and be merged into it, given the theme might want to style and control the plugin's blocks specifically, it should supercede if it's targeting those blocks.

Any suggestions for how the API might work from a plugin's perspective? The merging is fairly trivial, so it's more about the ergonomics. Consider also that WordPress bundles a theme.json as well for reference. There's been some requests to unload that bundled fallback before, so that also needs to be taken into account.

[nerrad]

I think the plugin should come before the theme as a fallback and be merged into it

Agreed, what I listed in the hierarchy flow is intended to represent priority of control from left to right. So, user overrides blocks which override theme which override plugin (I may be wrong on the blocks -> theme order, I think that might have changed recently?)

Any suggestions for how the API might work from a plugin's perspective?

I'm not sure what specifically you're asking about here? I'm guessing this isn't a question about how the plugin theme.json would be surfaced to WordPress?

Consider also that WordPress bundles a theme.json as well for reference.

Yes, I see that, and the theme takes precedence over anything defined by core's theme.json. I think it would make sense to have the plugin sit between core and the theme in merging order.

There's been some requests to unload that bundled fallback before, so that also needs to be taken into account.

Unload as in remove it completely, or to have an interface for external control over unloading it?

[mtias]

Got it, was reading the sequence wrong. Unload as being able to remove it if you want to supply your own without any dependencies or fallbacks.

I'm asking how should a plugin register or make its json file available, assuming it'd exist as a separate file.

[nerrad]

I'm asking how should a plugin register or make its json file available, assuming it'd exist as a separate file.

That's what I was addressing in my original comment. Ideally I think the plugin shouldn't need to explicitly register it other than maybe an option in the plugin header and then having the theme.json in a indicated path. So for instance maybe something like this for WooCommerce:

/**
 * Plugin Name: WooCommerce
 * Plugin URI: https://woocommerce.com/
 * Description: An eCommerce toolkit that helps you sell anything. Beautifully.
 * Version: 6.5.1
 * Author: Automattic
 * Author URI: https://woocommerce.com
 * Text Domain: woocommerce
 * Domain Path: /i18n/languages/
 * theme.json Path: /theme
 * Requires at least: 5.7
 * Requires PHP: 7.2
 *
 * @package WooCommerce
 */

The above would signal to WordPress core when parsing the plugin header on plugin activation/update that:

• The plugin has a theme.json file.
• It's located in the theme folder (relative to the plugin's root folder).

WordPress core could just register the paths for all plugins indicating they have a theme.json and then use that to load and merge when the initial resolution of all theme.json files happens on WP_Theme_JSON_Resolver::get_merged_data. Of course, we'd also have to account for when the resolution cache is cleared.

[luisherranz]

I love the idea.

Two thoughts:

1. I'd import it automatically if it exists. I don't see much value in making it opt-in when it's a new file that didn't exist previously.

2. If we have block.json and theme.json, I'd call this one plugin.json. That way, it could have its own version and schema. And there may be settings from theme.json that won't make sense in a plugin and vice versa.

[gziolo]

This is a fascinating idea. One additional consideration would be merging settings from multiple plugins.

Styles specified in the theme.json of a plugin, would have lower priority than the styles from the theme's theme.json and user styles.
This way, plugins can specify the default styles of their blocks in their theme.json and themes can override the styles from their theme.json.

With that, we would also need to figure out how to ensure that settings from multiple plugins are processed and merged in a predictable way.

If we have block.json and theme.json, I'd call this one plugin.json. That way, it could have its version and schema. And there may be settings from theme.json that won't make sense in a plugin and vice versa.

I don't have a formed opinion about the name of the file. I only wanted to surface potential challenges if we were to use translatable fields. We would have to create the list of translatable fields and implement the extraction of translations from plugin.json in WP CLI. I'm not sure how quickly we would run into that issue, but it's also worth emphasizing that we don't know how much the theme.json for plugins would overlap with theme.json from themes and how complex the merging strategy might become.

[nerrad]

The latest comments have raised additional questions. I'm still thinking through this but wanted to at least document them here in case others have answers/thoughts. I definitely think we should keep the initial scope fairly limited, but some of the questions raised could influence the initial structure of this, hence I'm asking.

• Should the plugin-provided properties only allow enhancing only a subset of potential theme.json properties? If so which? Keep in mind, theme.json would always override what is provided by the plugin.
• Should this be named differently and allow for potential separate versioning and other potential future uses?
• If multiple plugins provide the same properties, how do we handle merging them? Which plugin would "win" in any possible merge conflicts?
• Do we implement the ability to completely unload the default merging strategy (and potentially replace it) as a part of work on this issue?

I'll leave a comment in this issue at some point once I've had a chance to think through the implications for various answers to the above questions.

[luisherranz]

It's not that a plugin's theme.json like the one described here would only serve to configure the default styles of its blocks, but as that was the use case Albert was referring to when he opened this issue, I think it'd be interesting if you could take a look at #41873. It's also trying to solve that problem, but by letting plugins define those default styles in their block.json file instead.

• Move block css from supports > __experimentalStyle to a top level style key in block.json #41873

I'd love to hear what you think and how it overlaps with your needs here.