Adding doc comments

WordPress · Aug 1, 2024 · ef96fb1 · ef96fb1
1 parent 43e9107
commit ef96fb1
Showing 1 changed file with 24 additions and 4 deletions.
diff --git a/packages/block-editor/src/components/global-styles/utils.js b/packages/block-editor/src/components/global-styles/utils.js
@@ -526,12 +526,24 @@ export function getBlockStyleVariationSelector( variation, blockSelector ) {
 	return result.join( ',' );
 }
 
+/**
+ * Converts style preset values `var:` to CSS custom var values.
+ *
+ * Example:
+ *
+ * compileStyleValue( 'var:preset|color|primary' ) // returns 'var(--wp--color-primary)'
+ *
+ * @param {string} uncompiledValue A block style value.
+ * @return {string} The compiled, or original value.
+ */
 export function compileStyleValue( uncompiledValue ) {
 	const VARIABLE_REFERENCE_PREFIX = 'var:';
-	const VARIABLE_PATH_SEPARATOR_TOKEN_ATTRIBUTE = '|';
-	const VARIABLE_PATH_SEPARATOR_TOKEN_STYLE = '--';
-
-	if ( uncompiledValue?.startsWith?.( VARIABLE_REFERENCE_PREFIX ) ) {
+	if (
+		'string' === typeof uncompiledValue &&
+		uncompiledValue?.startsWith?.( VARIABLE_REFERENCE_PREFIX )
+	) {
+		const VARIABLE_PATH_SEPARATOR_TOKEN_ATTRIBUTE = '|';
+		const VARIABLE_PATH_SEPARATOR_TOKEN_STYLE = '--';
 		const variable = uncompiledValue
 			.slice( VARIABLE_REFERENCE_PREFIX.length )
 			.split( VARIABLE_PATH_SEPARATOR_TOKEN_ATTRIBUTE )
@@ -541,6 +553,14 @@ export function compileStyleValue( uncompiledValue ) {
 	return uncompiledValue;
 }
 
+/**
+ * Resolves ref values in theme JSON.
+ *
+ * @param {Object|string} ruleValue    A block style value that may contain a reference to a theme.json value.
+ * @param {Object}        tree         A theme.json object.
+ * @param {*}             defaultValue Optional default value to return if the resolved value is nullish.
+ * @return {*|string} The resolved value, the defaultValue or incoming ruleValue.
+ */
 export function getResolvedRefValue( ruleValue, tree, defaultValue ) {
 	if ( typeof ruleValue !== 'string' && ruleValue?.ref ) {
 		const refPath = ruleValue.ref.split( '.' );