Enable alpha on Block Inspector Color ToolsPanel (#37731)

* Initial commit: passing enableAlpha=true to the underlying ColorPicker component from the color tools panel.

* Show a warning in the color panel where either the text or background color has transparency.
Adding tests.
Updating README.md to reflect the reality that colord does not check the contrast of colors with alpha transparency in our implementation.

* enableContrastChecking if enableAlpha is true
only show the transparency warning where the text color alpha is < 1
ensure the readability/contrast warning takes precedence over the transparency warning

* Rename enable alpha prop to remove the experimental prefix

packages/block-editor/src/components/contrast-checker/README.md

@@ -1,6 +1,8 @@
 # ContrastChecker
 
-ContrastChecker component determines if contrast for text styles is sufficient (WCAG 2.0 AA) when used with a given background color. ContrastCheker also accounts for background color transparency (alpha) as well as font sizes.
+ContrastChecker component determines if contrast for text styles is sufficient (WCAG 2.0 AA) when used with a given background color. 
+
+ContrastChecker also accounts for font sizes.
 
 A notice will be rendered if the color combination of text and background colors are low.
 

packages/block-editor/src/components/contrast-checker/index.js

@@ -20,22 +20,31 @@ function ContrastCheckerMessage( {
 	colordTextColor,
 	backgroundColor,
 	textColor,
+	shouldShowTransparencyWarning,
 } ) {
-	const msg =
-		colordBackgroundColor.brightness() < colordTextColor.brightness()
-			? __(
-					'This color combination may be hard for people to read. Try using a darker background color and/or a brighter text color.'
-			  )
-			: __(
-					'This color combination may be hard for people to read. Try using a brighter background color and/or a darker text color.'
-			  );
+	let msg = '';
+	if ( shouldShowTransparencyWarning ) {
+		msg = __( 'Transparent text may be hard for people to read.' );
+	} else {
+		msg =
+			colordBackgroundColor.brightness() < colordTextColor.brightness()
+				? __(
+						'This color combination may be hard for people to read. Try using a darker background color and/or a brighter text color.'
+				  )
+				: __(
+						'This color combination may be hard for people to read. Try using a brighter background color and/or a darker text color.'
+				  );
+	}
 
 	// Note: The `Notice` component can speak messages via its `spokenMessage`
 	// prop, but the contrast checker requires granular control over when the
 	// announcements are made. Notably, the message will be re-announced if a
 	// new color combination is selected and the contrast is still insufficient.
 	useEffect( () => {
-		speak( __( 'This color combination may be hard for people to read.' ) );
+		const speakMsg = shouldShowTransparencyWarning
+			? __( 'Transparent text may be hard for people to read.' )
+			: __( 'This color combination may be hard for people to read.' );
+		speak( speakMsg );
 	}, [ backgroundColor, textColor ] );
 
 	return (
@@ -58,6 +67,7 @@ function ContrastChecker( {
 	fontSize, // font size value in pixels
 	isLargeText,
 	textColor,
+	enableAlphaChecker = false,
 } ) {
 	if (
 		! ( backgroundColor || fallbackBackgroundColor ) ||
@@ -69,28 +79,46 @@ function ContrastChecker( {
 		backgroundColor || fallbackBackgroundColor
 	);
 	const colordTextColor = colord( textColor || fallbackTextColor );
+	const textColorHasTransparency = colordTextColor.alpha() < 1;
+	const backgroundColorHasTransparency = colordBackgroundColor.alpha() < 1;
 	const hasTransparency =
-		colordBackgroundColor.alpha() !== 1 || colordTextColor.alpha() !== 1;
+		textColorHasTransparency || backgroundColorHasTransparency;
+	const isReadable = colordTextColor.isReadable( colordBackgroundColor, {
+		level: 'AA',
+		size:
+			isLargeText || ( isLargeText !== false && fontSize >= 24 )
+				? 'large'
+				: 'small',
+	} );
 
-	if (
-		hasTransparency ||
-		colordTextColor.isReadable( colordBackgroundColor, {
-			level: 'AA',
-			size:
-				isLargeText || ( isLargeText !== false && fontSize >= 24 )
-					? 'large'
-					: 'small',
-		} )
-	) {
+	// Don't show the message if the text is readable AND there's no transparency.
+	// This is the default.
+	if ( isReadable && ! hasTransparency ) {
 		return null;
 	}
 
+	if ( hasTransparency ) {
+		if (
+			// If there's transparency, don't show the message if the alpha checker is disabled.
+			! enableAlphaChecker ||
+			// If the alpha checker is enabled, we only show the warning if the text has transparency.
+			( isReadable && ! textColorHasTransparency )
+		) {
+			return null;
+		}
+	}
+
 	return (
 		<ContrastCheckerMessage
 			backgroundColor={ backgroundColor }
 			textColor={ textColor }
 			colordBackgroundColor={ colordBackgroundColor }
 			colordTextColor={ colordTextColor }
+			// Flag to warn about transparency only if the text is otherwise readable according to colord
+			// to ensure the readability warnings take precedence.
+			shouldShowTransparencyWarning={
+				isReadable && textColorHasTransparency
+			}
 		/>
 	);
 }

packages/block-editor/src/components/contrast-checker/test/index.js

@@ -50,6 +50,20 @@ describe( 'ContrastChecker', () => {
 		expect( wrapper.html() ).toBeNull();
 	} );
 
+	test( 'should render null when the colors meet AA WCAG guidelines and alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ backgroundColor }
+				textColor={ textColor }
+				isLargeText={ isLargeText }
+				enableAlphaChecker={ true }
+			/>
+		);
+
+		expect( speak ).not.toHaveBeenCalled();
+		expect( wrapper.html() ).toBeNull();
+	} );
+
 	test( 'should render component when the colors do not meet AA WCAG guidelines.', () => {
 		const wrapper = mount(
 			<ContrastChecker
@@ -258,4 +272,55 @@ describe( 'ContrastChecker', () => {
 
 		expect( speak ).toHaveBeenCalledTimes( 2 );
 	} );
+
+	// enableAlphaChecker tests
+	test( 'should render component when the colors meet AA WCAG guidelines but the text color only has alpha transparency with alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ backgroundColor }
+				textColor={ 'rgba(0,0,0,0.9)' }
+				isLargeText={ isLargeText }
+				enableAlphaChecker={ true }
+			/>
+		);
+
+		expect( speak ).toHaveBeenCalledWith(
+			'Transparent text may be hard for people to read.'
+		);
+		expect( wrapper.find( Notice ).children().text() ).toBe(
+			'Transparent text may be hard for people to read.'
+		);
+	} );
+
+	test( 'should render null when the colors meet AA WCAG guidelines but the background color only has alpha transparency with alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ 'rgba(255,255,255,0.7)' }
+				textColor={ textColor }
+				isLargeText={ isLargeText }
+				enableAlphaChecker={ true }
+			/>
+		);
+
+		expect( speak ).not.toHaveBeenCalled();
+		expect( wrapper.html() ).toBeNull();
+	} );
+
+	test( 'should render component when the colors meet AA WCAG guidelines but all colors have alpha transparency with alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ 'rgba(255,255,255,0.7)' }
+				textColor={ 'rgba(0,0,0,0.7)' }
+				isLargeText={ isLargeText }
+				enableAlphaChecker={ true }
+			/>
+		);
+
+		expect( speak ).toHaveBeenCalledWith(
+			'Transparent text may be hard for people to read.'
+		);
+		expect( wrapper.find( Notice ).children().text() ).toBe(
+			'Transparent text may be hard for people to read.'
+		);
+	} );
 } );

packages/block-editor/src/hooks/color-panel.js

@@ -17,6 +17,7 @@ function getComputedStyle( node ) {
 }
 
 export default function ColorPanel( {
+	enableAlpha = false,
 	settings,
 	clientId,
 	enableContrastChecking = true,
@@ -60,13 +61,15 @@ export default function ColorPanel( {
 				initialOpen={ false }
 				settings={ settings }
 				showTitle={ showTitle }
+				enableAlpha={ enableAlpha }
 				__experimentalHasMultipleOrigins
 				__experimentalIsRenderedInSidebar
 			>
 				{ enableContrastChecking && (
 					<ContrastChecker
 						backgroundColor={ detectedBackgroundColor }
 						textColor={ detectedColor }
+						enableAlphaChecker={ enableAlpha }
 					/>
 				) }
 			</PanelColorGradientSettings>

packages/block-editor/src/hooks/color.js

@@ -371,13 +371,14 @@ export function ColorEdit( props ) {
 		props.setAttributes( { style: newStyle } );
 	};
 
+	const enableContrastChecking =
+		Platform.OS === 'web' && ! gradient && ! style?.color?.gradient;
+
 	return (
 		<ColorPanel
-			enableContrastChecking={
-				// Turn on contrast checker for web only since it's not supported on mobile yet.
-				Platform.OS === 'web' && ! gradient && ! style?.color?.gradient
-			}
+			enableContrastChecking={ enableContrastChecking }
 			clientId={ props.clientId }
+			enableAlpha={ true }
 			settings={ [
 				...( hasTextColor
 					? [