Add support for relative paths to theme assets in theme.json

[ramonopoly]

The end goal is to allow theme devs to add relative paths to assets in theme.json.

For example,

{
	"$schema": "https://schemas.wp.org/trunk/theme.json",
	"version": 2,
	"settings": {
		"appearanceTools": true
	},
	"styles": {
		"background": {
			"backgroundImage": {
				"url": "img/untitled.png"
			}
		}
	}
}

This is advantageous in that themes can remain portable across WordPress instances.

These paths must be resolved, preferably by ​get_theme_file_uri so that child themes can inherit and or overwrite asset paths.

The resolved, absolute paths would be used in the CSS output.

To preserve the theme.json object across states, so that the resolved path is not saved to the WordPress database (for example as a user style or style revisions) the resolved path should only be used when outputting CSS.

This is true for the frontend as well as the editor.

In the frontend, file resolution could occur in wp_get_global_stylesheet.

However in the editor, there is no equivalent to get_theme_file_uri in the clientside JS code.

Therefore, to keep things performant in the editor, I'm thinking it would be useful to resolve the relative paths in PHP and send them to the frontend as part of the Global styles REST API controllers: WP_REST_Global_Styles_Controller_Gutenberg and WP_REST_Global_Styles_Revisions_Controller, via a public static method in WP_Theme_JSON_Resolver to handle the file resolution.

This Gutenberg PR:
​Background image: add support for relative theme path URLs in top-level theme.json styles #61271

demonstrates a proof of concept.

It would be helpful to get advice on that approach or alternative paths to reach the goal.

Thank you!

[ramonopoly]

Therefore, to keep things performant in the editor, I'm thinking it would be useful to resolve the relative paths in PHP and send them to the frontend as part of the Global styles REST API controllers:

In the ​proof of concept I've added the following to the responses:

"_links": {
    "wp:theme-file-uris": [
        {
            "name": "img/budgie3.jpg",
            "href": "http://localhost:8888/wp-content/themes/emptytheme/img/budgie3.jpg",
            "target": "styles.background.backgroundImage.url",
            "type": "image/jpeg"
        }
    ]
}

"href", "type" and "name" are HAL reserved attributes. "target", a valid link attribute, I added to represent the path in the theme.json tree to the value that needs to be replaced.

Some responses are collections of global styles objects. For example WP_REST_Global_Styles_Controller_Gutenberg::get_theme_items and WP_REST_Global_Styles_Revisions_Controller::get_items. Therefore a property can't be added to the top-level response.

To get around this I've added _links to each item in the collection.

I was going to suggest adding another, custom property to the ​global styles object schema if folks think links to image URIs shouldn't live under _links. I tend to think that HAL is flexible enough to accommodate, but keen to hear others' thoughts.

[ramonopoly]

However in the editor, there is no equivalent to get_theme_file_uri in the clientside JS code.

There was an ​attempt to implement one, however the nature of the async code meant that CSS could not be generated synchronously.