style-engine-gutenberg.php in Gutenberg 23.2.0, at build/scripts/style-engine/style-engine-gutenberg.php

157 lines 6.6 KB Raw Download Zip

1	<?php
2	/**
3	* Style engine: Public functions
4	*
5	* This file contains a variety of public functions developers can use to interact with
6	* the Style Engine API.
7	*
8	* @package gutenberg
9	*/
10
11	/**
12	* Global public interface method to generate styles from a single style object, e.g.,
13	* the value of a block's attributes.style object or the top level styles in theme.json.
14	* See: https://developer.wordpress.org/block-editor/reference-guides/theme-json-reference/theme-json-living/#styles and
15	* https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/
16	*
17	* Example usage:
18	*
19	* $styles = gutenberg_style_engine_get_styles( array( 'color' => array( 'text' => '#cccccc' ) ) );
20	* // Returns `array( 'css' => 'color: #cccccc', 'declarations' => array( 'color' => '#cccccc' ), 'classnames' => 'has-color' )`.
21	*
22	* @since 6.1.0
23	*
24	* @param array $block_styles The style object.
25	* @param array $options {
26	* Optional. An array of options. Default empty array.
27	*
28	* @type string\|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is `null`.
29	* When set, the Style Engine will attempt to store the CSS rules, where a selector is also passed.
30	* @type bool $convert_vars_to_classnames Whether to skip converting incoming CSS var patterns, e.g., `var:preset\|<PRESET_TYPE>\|<PRESET_SLUG>`, to var( --wp--preset--* ) values. Default `false`.
31	* @type string $selector Optional. When a selector is passed, the value of `$css` in the return value will comprise a full CSS rule `$selector { ...$css_declarations }`,
32	* otherwise, the value will be a concatenated string of CSS declarations.
33	* }
34	*
35	* @return array {
36	* @type string $css A CSS ruleset or declarations block formatted to be placed in an HTML `style` attribute or tag.
37	* @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
38	* @type string $classnames Classnames separated by a space.
39	* }
40	*/
41	function gutenberg_style_engine_get_styles( $block_styles, $options = array() ) {
42	$options = wp_parse_args(
43	$options,
44	array(
45	'selector' => null,
46	'context' => null,
47	'convert_vars_to_classnames' => false,
48	)
49	);
50
51	$parsed_styles = WP_Style_Engine_Gutenberg::parse_block_styles( $block_styles, $options );
52
53	// Output.
54	$styles_output = array();
55
56	if ( ! empty( $parsed_styles['declarations'] ) ) {
57	$styles_output['css'] = WP_Style_Engine_Gutenberg::compile_css( $parsed_styles['declarations'], $options['selector'] );
58	$styles_output['declarations'] = $parsed_styles['declarations'];
59	if ( ! empty( $options['context'] ) ) {
60	WP_Style_Engine_Gutenberg::store_css_rule( $options['context'], $options['selector'], $parsed_styles['declarations'] );
61	}
62	}
63
64	if ( ! empty( $parsed_styles['classnames'] ) ) {
65	$styles_output['classnames'] = implode( ' ', array_unique( $parsed_styles['classnames'] ) );
66	}
67
68	return array_filter( $styles_output );
69	}
70
71	/**
72	* Returns compiled CSS from a collection of selectors and declarations.
73	* Useful for returning a compiled stylesheet from any collection of CSS selector + declarations.
74	*
75	* Example usage:
76	* $css_rules = array( array( 'selector' => '.elephant-are-cool', 'declarations' => array( 'color' => 'gray', 'width' => '3em' ) ) );
77	* $css = gutenberg_style_engine_get_stylesheet_from_css_rules( $css_rules );
78	* // Returns `.elephant-are-cool{color:gray;width:3em}`.
79	*
80	* @since 6.1.0
81	*
82	* @param array $css_rules {
83	* Required. A collection of CSS rules.
84	*
85	* @type array ...$0 {
86	* @type string $rules_group A parent CSS selector in the case of nested CSS, or a CSS nested @rule, such as `@media (min-width: 80rem)` or `@layer module`.
87	* @type string $selector A CSS selector.
88	* @type string[] $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ).
89	* }
90	* }
91	* @param array $options {
92	* Optional. An array of options. Default empty array.
93	*
94	* @type string\|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
95	* When set, the Style Engine will attempt to store the CSS rules.
96	* @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
97	* @type bool $prettify Whether to add new lines and indents to output. Default is to inherit the value of the global constant `SCRIPT_DEBUG`, if it is defined.
98	* }
99	*
100	* @return string A string of compiled CSS declarations, or empty string.
101	*/
102	function gutenberg_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = array() ) {
103	if ( empty( $css_rules ) ) {
104	return '';
105	}
106
107	$options = wp_parse_args(
108	$options,
109	array(
110	'context' => null,
111	)
112	);
113
114	$css_rule_objects = array();
115	foreach ( $css_rules as $css_rule ) {
116	if ( empty( $css_rule['selector'] ) \|\| empty( $css_rule['declarations'] ) \|\| ! is_array( $css_rule['declarations'] ) ) {
117	continue;
118	}
119
120	$rules_group = $css_rule['rules_group'] ?? null;
121	if ( ! empty( $options['context'] ) ) {
122	WP_Style_Engine_Gutenberg::store_css_rule( $options['context'], $css_rule['selector'], $css_rule['declarations'], $rules_group );
123	}
124
125	$css_rule_objects[] = new WP_Style_Engine_CSS_Rule_Gutenberg( $css_rule['selector'], $css_rule['declarations'], $rules_group );
126	}
127
128	if ( empty( $css_rule_objects ) ) {
129	return '';
130	}
131
132	return WP_Style_Engine_Gutenberg::compile_stylesheet_from_css_rules( $css_rule_objects, $options );
133	}
134
135	/**
136	* Returns compiled CSS from a store, if found.
137	*
138	* @since 6.1.0
139	*
140	* @param string $context A valid context name, corresponding to an existing store key.
141	* @param array $options {
142	* Optional. An array of options. Default empty array.
143	*
144	* @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
145	* @type bool $prettify Whether to add new lines and indents to output. Default is to inherit the value of the global constant `SCRIPT_DEBUG`, if it is defined.
146	* }
147	*
148	* @return string A compiled CSS string.
149	*/
150	function gutenberg_style_engine_get_stylesheet_from_context( $context, $options = array() ) {
151	if ( empty( $context ) ) {
152	return '';
153	}
154
155	return WP_Style_Engine_Gutenberg::compile_stylesheet_from_css_rules( WP_Style_Engine_Gutenberg::get_store( $context )->get_all_rules(), $options );
156	}
157