gutenberg / build / scripts / style-engine / style-engine-gutenberg.php

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

163 lines 6.9 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[]\|WP_Style_Engine_CSS_Declarations_Gutenberg $declarations An associative array of CSS definitions, e.g., array( "$property" => "$value", "$property" => "$value" ),
89	* or a WP_Style_Engine_CSS_Declarations_Gutenberg object.
90	* }
91	* }
92	* @param array $options {
93	* Optional. An array of options. Default empty array.
94	*
95	* @type string\|null $context An identifier describing the origin of the style object, e.g., 'block-supports' or 'global-styles'. Default is 'block-supports'.
96	* When set, the Style Engine will attempt to store the CSS rules.
97	* @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
98	* @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.
99	* }
100	*
101	* @return string A string of compiled CSS declarations, or empty string.
102	*/
103	function gutenberg_style_engine_get_stylesheet_from_css_rules( $css_rules, $options = array() ) {
104	if ( empty( $css_rules ) ) {
105	return '';
106	}
107
108	$options = wp_parse_args(
109	$options,
110	array(
111	'context' => null,
112	)
113	);
114
115	$css_rule_objects = array();
116	foreach ( $css_rules as $css_rule ) {
117	$declarations = $css_rule['declarations'] ?? null;
118	if (
119	empty( $css_rule['selector'] ) \|\|
120	empty( $declarations ) \|\|
121	( ! is_array( $declarations ) && ! $declarations instanceof WP_Style_Engine_CSS_Declarations_Gutenberg )
122	) {
123	continue;
124	}
125
126	$rules_group = $css_rule['rules_group'] ?? null;
127	if ( ! empty( $options['context'] ) ) {
128	WP_Style_Engine_Gutenberg::store_css_rule( $options['context'], $css_rule['selector'], $declarations, $rules_group );
129	}
130
131	$css_rule_objects[] = new WP_Style_Engine_CSS_Rule_Gutenberg( $css_rule['selector'], $declarations, $rules_group );
132	}
133
134	if ( empty( $css_rule_objects ) ) {
135	return '';
136	}
137
138	return WP_Style_Engine_Gutenberg::compile_stylesheet_from_css_rules( $css_rule_objects, $options );
139	}
140
141	/**
142	* Returns compiled CSS from a store, if found.
143	*
144	* @since 6.1.0
145	*
146	* @param string $context A valid context name, corresponding to an existing store key.
147	* @param array $options {
148	* Optional. An array of options. Default empty array.
149	*
150	* @type bool $optimize Whether to optimize the CSS output, e.g., combine rules. Default is `false`.
151	* @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.
152	* }
153	*
154	* @return string A compiled CSS string.
155	*/
156	function gutenberg_style_engine_get_stylesheet_from_context( $context, $options = array() ) {
157	if ( empty( $context ) ) {
158	return '';
159	}
160
161	return WP_Style_Engine_Gutenberg::compile_stylesheet_from_css_rules( WP_Style_Engine_Gutenberg::get_store( $context )->get_all_rules(), $options );
162	}
163