`wp_get_global_styles`: allow transform variables into its raw values

[oandregal]

Related Gutenberg ticket: ​https://github.com/WordPress/gutenberg/issues/49712.

In some scenarios (mobile, mail, etc.) the CSS Custom Properties are not supported and/or it is more convenient to operate with the raw values they represent. However, wp_get_global_styles, the public API for styles coming from theme.json, returns the values as they are.

Core should provide a way to transform the CSS Custom Properties into the raw values they represent.

For example, the following data coming from a theme.json:

"core/post-terms": {
    "typography": { "fontSize": "var(--wp--preset--font-size--small)" }
}

The expected result for wp_get_global_styles is:

<?php
(
    [typography] => Array( [fontSize] => var(--wp--preset--font-size--small) )
)

By transforming variables into values, the expected result would be (provided the small font size preset had been defined as 12px):

<?php
(
    [typography] => Array( [fontSize] => "12px" )
)

Both scenarios need to be supported and the normal path is to return the CSS Custom Properties.

Trac ticket https://core.trac.wordpress.org/ticket/58588
Related Gutenberg ticket ​https://github.com/WordPress/gutenberg/issues/49712

This PR backports ​https://github.com/WordPress/gutenberg/pull/50484

## What?

This PR addresses the changes explained in the corresponding trac and gutenberg tickets by introducing the transforms key to the $context parameter as part of wp_get_global_styles function:

From a theme.json that contains the following data:

{
  "core/post-terms": {
    "typography": { "fontSize": "var(--wp--preset--font-size--small)" }
  }
}

Using the public API to retrieve styles:

wp_get_global_styles( array(), array( 
    'block_name' => 'core/post-terms',
    'transforms' => array( 'resolve-variables' ) 
    )
 );

should return:

"core/post-terms": {
    "typography": { "fontSize": "12px" }
}

And using the normal path (note there's no transforms key):

wp_get_global_styles( array(), array( 
    'block_name' => 'core/post-terms',
    )
 );

should return the Custom CSS Property as before:

"core/post-terms": {
    "typography": { "fontSize": "var(--wp--preset--font-size--small)" }
}

## Why?

There are some usages of the wp_get_global_styles where the consumer is interested in the values of the CSS rules and not the variables.

## How?

By adding a new transform key to the existing $context parameter in the wp_get_global_styles function.

## Testing Instructions

• Use TwentyTwenthyThree.
• Then, somewhere, retrieve and log some value that uses CSS Custom Properties using the new transforms key. For example, paste the following in functions.php of the theme:

add_action( 'init', function(){
        error_log( print_r( wp_get_global_styles( array(), array('block_name'=>'core/post-terms', 'transforms' => array( 'resolve-variables' ) ) ), true ) );
} );

The expected output is the value of the small font-size property.

cc @ramonjd @tellthemachines

I'm seeing an error TimeoutError: Navigation timeout of 30000 ms exceeded for the tests/e2e/specs/gutenberg-plugin.test.js and tests/e2e/specs/dashboard.test.js e2e.

This is unrelated to this code change. Note that the new parameter for wp_get_global_styles is not in use by core right now, it's going to be used by Gutenberg and 3rd parties.

I've also seen it failing in trunk: at least since ​https://github.com/WordPress/wordpress-develop/actions/runs/5330603048/jobs/9663294856 Though that PR was reverted and the error was still happening after, as late as in ​https://github.com/WordPress/wordpress-develop/actions/runs/5330603048/jobs/9663294856.

Shared in core slack channel (​link), to increase visibility of this issue.

Looking good to me.

I tried with some other blocks:

array(2) {
  ["typography"]=>
  array(1) {
    ["fontSize"]=>
    string(35) "var(--wp--preset--font-size--large)"
  }
  ["spacing"]=>
  array(1) {
    ["margin"]=>
    array(1) {
      ["bottom"]=>
      string(30) "var(--wp--preset--spacing--40)"
    }
  }
}

array(2) {
  ["typography"]=>
  array(1) {
    ["fontSize"]=>
    string(60) "clamp(1.75rem, 1.75rem + ((1vw - 0.2rem) * 0.227), 1.875rem)"
  }
  ["spacing"]=>
  array(1) {
    ["margin"]=>
    array(1) {
      ["bottom"]=>
      string(55) "clamp(1.8rem, 1.8rem + ((1vw - 0.48rem) * 2.885), 3rem)"
    }
  }
}

As well as passing no path in order to render the entire, transformed theme.json tree.

All presets are resolved.

I can't see any regressions in existing theme json functionality.

The E2E tests have been flaky for most of the week. Agree that they're not related to this PR.

Once the refs to _Gutenberg classes are changed, I think this LGTM.

Committed in https://core.trac.wordpress.org/changeset/55986.

Trac is having a hard time listing the revision 55986, so the link may not work inmediately. Apparently (​slack thread), it's something that happens from time to time and will be listed after the next commit.