Fix inline docs and add tests for color utils

packages/block-editor/README.md

@@ -208,7 +208,7 @@ _Parameters_
 
 _Returns_
 
--   `string`: String with the class corresponding to the color in the provided context.
+-   `?string`: String with the class corresponding to the color in the provided context. Returns undefined if either colorContextName or colorSlug are not provided.
 
 <a name="getColorObjectByAttributeValues" href="#getColorObjectByAttributeValues">#</a> **getColorObjectByAttributeValues**
 
@@ -223,7 +223,7 @@ _Parameters_
 
 _Returns_
 
--   `?string`: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined.
+-   `?Object`: If definedColor is passed and the name is found in colors, the color object exactly as set by the theme or editor defaults is returned. Otherwise, an object that just sets the color is defined.
 
 <a name="getColorObjectByColorValue" href="#getColorObjectByColorValue">#</a> **getColorObjectByColorValue**
 
@@ -236,7 +236,7 @@ _Parameters_
 
 _Returns_
 
--   `?string`: Returns the color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement.
+-   `?Object`: Color object included in the colors array whose color property equals colorValue. Returns undefined if no color object matches this requirement.
 
 <a name="getFontSize" href="#getFontSize">#</a> **getFontSize**
 

packages/block-editor/src/components/colors/test/utils.js

@@ -0,0 +1,83 @@
+/**
+ * Internal dependencies
+ */
+import {
+	getColorObjectByAttributeValues,
+	getColorObjectByColorValue,
+	getColorClassName,
+} from '../utils';
+
+describe( 'color utils', () => {
+	describe( 'getColorObjectByAttributeValues', () => {
+		it( 'should return the custom color object when there is no definedColor', () => {
+			const colors = [
+				{ slug: 'red' },
+				{ slug: 'green' },
+				{ slug: 'blue' },
+			];
+			const customColor = '#ffffff';
+
+			expect( getColorObjectByAttributeValues( colors, undefined, customColor ) ).toEqual( { color: customColor } );
+		} );
+
+		it( 'should return the custom color object when definedColor was not found', () => {
+			const colors = [
+				{ slug: 'red' },
+				{ slug: 'green' },
+				{ slug: 'blue' },
+			];
+			const definedColor = 'purple';
+			const customColor = '#ffffff';
+
+			expect( getColorObjectByAttributeValues( colors, definedColor, customColor ) ).toEqual( { color: customColor } );
+		} );
+
+		it( 'should return the found color object', () => {
+			const colors = [
+				{ slug: 'red' },
+				{ slug: 'green' },
+				{ slug: 'blue' },
+			];
+			const definedColor = 'blue';
+			const customColor = '#ffffff';
+
+			expect( getColorObjectByAttributeValues( colors, definedColor, customColor ) ).toEqual( { slug: 'blue' } );
+		} );
+	} );
+
+	describe( 'getColorObjectByColorValue', () => {
+		it( 'should return undefined if the given color was not found', () => {
+			const colors = [
+				{ slug: 'red', color: '#ff0000' },
+				{ slug: 'green', color: '#00ff00' },
+				{ slug: 'blue', color: '#0000ff' },
+			];
+
+			expect( getColorObjectByColorValue( colors, '#ffffff' ) ).toBeUndefined();
+		} );
+
+		it( 'should return a color object for the given color value', () => {
+			const colors = [
+				{ slug: 'red', color: '#ff0000' },
+				{ slug: 'green', color: '#00ff00' },
+				{ slug: 'blue', color: '#0000ff' },
+			];
+
+			expect( getColorObjectByColorValue( colors, '#00ff00' ) ).toEqual( { slug: 'green', color: '#00ff00' } );
+		} );
+	} );
+
+	describe( 'getColorClassName', () => {
+		it( 'should return undefined if colorContextName is missing', () => {
+			expect( getColorClassName( undefined, 'Light Purple' ) ).toBeUndefined();
+		} );
+
+		it( 'should return undefined if colorSlug is missing', () => {
+			expect( getColorClassName( 'background', undefined ) ).toBeUndefined();
+		} );
+
+		it( 'should return a class name with the color slug in kebab case', () => {
+			expect( getColorClassName( 'background', 'Light Purple' ) ).toBe( 'has-light-purple-background' );
+		} );
+	} );
+} );

packages/block-editor/src/components/colors/utils.js

@@ -12,7 +12,7 @@ import tinycolor from 'tinycolor2';
  * @param {?string} definedColor A string containing the color slug.
  * @param {?string} customColor  A string containing the customColor value.
  *
- * @return {?string} If definedColor is passed and the name is found in colors,
+ * @return {?Object} If definedColor is passed and the name is found in colors,
  *                   the color object exactly as set by the theme or editor defaults is returned.
  *                   Otherwise, an object that just sets the color is defined.
  */
@@ -35,7 +35,7 @@ export const getColorObjectByAttributeValues = ( colors, definedColor, customCol
 * @param {Array}   colors      Array of color objects as set by the theme or by the editor defaults.
 * @param {?string} colorValue  A string containing the color value.
 *
-* @return {?string} Returns the color object included in the colors array whose color property equals colorValue.
+* @return {?Object} Color object included in the colors array whose color property equals colorValue.
 *                   Returns undefined if no color object matches this requirement.
 */
 export const getColorObjectByColorValue = ( colors, colorValue ) => {
@@ -48,11 +48,12 @@ export const getColorObjectByColorValue = ( colors, colorValue ) => {
  * @param {string} colorContextName Context/place where color is being used e.g: background, text etc...
  * @param {string} colorSlug        Slug of the color.
  *
- * @return {string} String with the class corresponding to the color in the provided context.
+ * @return {?string} String with the class corresponding to the color in the provided context.
+ *                   Returns undefined if either colorContextName or colorSlug are not provided.
  */
 export function getColorClassName( colorContextName, colorSlug ) {
 	if ( ! colorContextName || ! colorSlug ) {
-		return;
+		return undefined;
 	}
 
 	return `has-${ kebabCase( colorSlug ) }-${ colorContextName }`;