@wordpress/block-editor 8.0.17 → 8.1.2-next.f435e9e01b.0

package/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.
 

package/src/components/contrast-checker/index.js

@@ -1,42 +1,129 @@
 /**
  * External dependencies
  */
-import { colord, extend } from 'colord';
-import namesPlugin from 'colord/plugins/names';
 import a11yPlugin from 'colord/plugins/a11y';
+import namesPlugin from 'colord/plugins/names';
+import { colord, extend } from 'colord';
 
 /**
  * WordPress dependencies
  */
-import { speak } from '@wordpress/a11y';
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import { Notice } from '@wordpress/components';
-import { useEffect } from '@wordpress/element';
+import { speak } from '@wordpress/a11y';
 
 extend( [ namesPlugin, a11yPlugin ] );
 
-function ContrastCheckerMessage( {
-	colordBackgroundColor,
-	colordTextColor,
+function ContrastChecker( {
 	backgroundColor,
+	fallbackBackgroundColor,
+	fallbackTextColor,
+	fallbackLinkColor,
+	fontSize, // font size value in pixels
+	isLargeText,
 	textColor,
+	linkColor,
+	enableAlphaChecker = false,
 } ) {
-	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.'
-			  );
+	const currentBackgroundColor = backgroundColor || fallbackBackgroundColor;
+
+	// Must have a background color.
+	if ( ! currentBackgroundColor ) {
+		return null;
+	}
+
+	const currentTextColor = textColor || fallbackTextColor;
+	const currentLinkColor = linkColor || fallbackLinkColor;
+
+	// Must have at least one text color.
+	if ( ! currentTextColor && ! currentLinkColor ) {
+		return null;
+	}
+
+	const textColors = [
+		{
+			color: currentTextColor,
+			description: __( 'text color' ),
+		},
+		{
+			color: currentLinkColor,
+			description: __( 'link color' ),
+		},
+	];
+	const colordBackgroundColor = colord( currentBackgroundColor );
+	const backgroundColorHasTransparency = colordBackgroundColor.alpha() < 1;
+	const backgroundColorBrightness = colordBackgroundColor.brightness();
+	const isReadableOptions = {
+		level: 'AA',
+		size:
+			isLargeText || ( isLargeText !== false && fontSize >= 24 )
+				? 'large'
+				: 'small',
+	};
+
+	let message = '';
+	let speakMessage = '';
+	for ( const item of textColors ) {
+		// If there is no color, go no further.
+		if ( ! item.color ) {
+			continue;
+		}
+		const colordTextColor = colord( item.color );
+		const isColordTextReadable = colordTextColor.isReadable(
+			colordBackgroundColor,
+			isReadableOptions
+		);
+		const textHasTransparency = colordTextColor.alpha() < 1;
+
+		// If the contrast is not readable.
+		if ( ! isColordTextReadable ) {
+			// Don't show the message if the background or text is transparent.
+			if ( backgroundColorHasTransparency || textHasTransparency ) {
+				continue;
+			}
+			message =
+				backgroundColorBrightness < colordTextColor.brightness()
+					? sprintf(
+							// translators: %s is a type of text color, e.g., "text color" or "link color"
+							__(
+								'This color combination may be hard for people to read. Try using a darker background color and/or a brighter %s.'
+							),
+							item.description
+					  )
+					: sprintf(
+							// translators: %s is a type of text color, e.g., "text color" or "link color"
+							__(
+								'This color combination may be hard for people to read. Try using a brighter background color and/or a darker %s.'
+							),
+							item.description
+					  );
+			speakMessage = __(
+				'This color combination may be hard for people to read.'
+			);
+			// Break from the loop when we have a contrast warning.
+			// These messages take priority over the transparency warning.
+			break;
+		}
+
+		// If there is no contrast warning and the text is transparent,
+		// show the transparent warning if alpha check is enabled.
+		if ( textHasTransparency && enableAlphaChecker ) {
+			message = __( 'Transparent text may be hard for people to read.' );
+			speakMessage = __(
+				'Transparent text may be hard for people to read.'
+			);
+		}
+	}
+
+	if ( ! message ) {
+		return null;
+	}
 
 	// 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.' ) );
-	}, [ backgroundColor, textColor ] );
+	speak( speakMessage );
 
 	return (
 		<div className="block-editor-contrast-checker">
@@ -45,54 +132,10 @@ function ContrastCheckerMessage( {
 				status="warning"
 				isDismissible={ false }
 			>
-				{ msg }
+				{ message }
 			</Notice>
 		</div>
 	);
 }
 
-function ContrastChecker( {
-	backgroundColor,
-	fallbackBackgroundColor,
-	fallbackTextColor,
-	fontSize, // font size value in pixels
-	isLargeText,
-	textColor,
-} ) {
-	if (
-		! ( backgroundColor || fallbackBackgroundColor ) ||
-		! ( textColor || fallbackTextColor )
-	) {
-		return null;
-	}
-	const colordBackgroundColor = colord(
-		backgroundColor || fallbackBackgroundColor
-	);
-	const colordTextColor = colord( textColor || fallbackTextColor );
-	const hasTransparency =
-		colordBackgroundColor.alpha() !== 1 || colordTextColor.alpha() !== 1;
-
-	if (
-		hasTransparency ||
-		colordTextColor.isReadable( colordBackgroundColor, {
-			level: 'AA',
-			size:
-				isLargeText || ( isLargeText !== false && fontSize >= 24 )
-					? 'large'
-					: 'small',
-		} )
-	) {
-		return null;
-	}
-
-	return (
-		<ContrastCheckerMessage
-			backgroundColor={ backgroundColor }
-			textColor={ textColor }
-			colordBackgroundColor={ colordBackgroundColor }
-			colordTextColor={ colordTextColor }
-		/>
-	);
-}
-
 export default ContrastChecker;

package/src/components/contrast-checker/index.native.js

@@ -0,0 +1,113 @@
+/**
+ * External dependencies
+ */
+import { Text, View } from 'react-native';
+import { colord, extend } from 'colord';
+import namesPlugin from 'colord/plugins/names';
+import a11yPlugin from 'colord/plugins/a11y';
+
+/**
+ * WordPress dependencies
+ */
+import { speak } from '@wordpress/a11y';
+import { __ } from '@wordpress/i18n';
+import { useEffect } from '@wordpress/element';
+import { usePreferredColorSchemeStyle } from '@wordpress/compose';
+import { Icon, warning } from '@wordpress/icons';
+/**
+ * Internal dependencies
+ */
+import styles from './style.scss';
+
+extend( [ namesPlugin, a11yPlugin ] );
+
+function ContrastCheckerMessage( {
+	colordBackgroundColor,
+	colordTextColor,
+	backgroundColor,
+	textColor,
+	msgStyle,
+} ) {
+	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.'
+			  );
+
+	// 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.' ) );
+	}, [ backgroundColor, textColor ] );
+
+	const iconStyle = usePreferredColorSchemeStyle(
+		styles[ 'block-editor-contrast-checker__icon' ],
+		styles[ 'block-editor-contrast-checker__icon-dark' ]
+	);
+
+	return (
+		<View style={ styles[ 'block-editor-contrast-checker' ] }>
+			<Icon style={ iconStyle } icon={ warning } />
+			<Text style={ msgStyle }>{ msg }</Text>
+		</View>
+	);
+}
+
+function ContrastChecker( {
+	backgroundColor,
+	fallbackBackgroundColor,
+	fallbackTextColor,
+	fontSize, // font size value in pixels
+	isLargeText,
+	textColor,
+} ) {
+	const msgStyle = usePreferredColorSchemeStyle(
+		styles[ 'block-editor-contrast-checker__notice' ],
+		styles[ 'block-editor-contrast-checker__notice-dark' ]
+	);
+
+	if (
+		! ( backgroundColor || fallbackBackgroundColor ) ||
+		! ( textColor || fallbackTextColor )
+	) {
+		return null;
+	}
+
+	const colordBackgroundColor = colord(
+		backgroundColor || fallbackBackgroundColor
+	);
+	const colordTextColor = colord( textColor || fallbackTextColor );
+
+	const hasTransparency =
+		colordBackgroundColor.alpha() !== 1 || colordTextColor.alpha() !== 1;
+
+	if (
+		hasTransparency ||
+		colordTextColor.isReadable( colordBackgroundColor, {
+			level: 'AA',
+			size:
+				isLargeText || ( isLargeText !== false && fontSize >= 24 )
+					? 'large'
+					: 'small',
+		} )
+	) {
+		return null;
+	}
+
+	return (
+		<ContrastCheckerMessage
+			backgroundColor={ backgroundColor }
+			textColor={ textColor }
+			colordBackgroundColor={ colordBackgroundColor }
+			colordTextColor={ colordTextColor }
+			msgStyle={ msgStyle }
+		/>
+	);
+}
+
+export default ContrastChecker;

package/src/components/contrast-checker/style.native.scss

@@ -0,0 +1,26 @@
+.block-editor-contrast-checker {
+	flex-direction: row;
+	align-items: center;
+	padding: 8px 0;
+	justify-content: space-between;
+}
+
+.block-editor-contrast-checker__notice {
+	font-size: 11px;
+	font-weight: 500;
+	color: $yellow-50;
+	flex: 1;
+}
+
+.block-editor-contrast-checker__notice-dark {
+	color: $yellow-30;
+}
+
+.block-editor-contrast-checker__icon {
+	color: $yellow-50;
+	margin-right: 5px;
+}
+
+.block-editor-contrast-checker__icon-dark {
+	color: $yellow-30;
+}

package/src/components/contrast-checker/test/index.js

@@ -21,11 +21,12 @@ jest.mock( '@wordpress/a11y', () => ( { speak: jest.fn() } ) );
 describe( 'ContrastChecker', () => {
 	const backgroundColor = '#ffffff';
 	const textColor = '#000000';
+	const linkColor = '#0040ff';
 	const isLargeText = true;
 	const fallbackBackgroundColor = '#fff';
 	const fallbackTextColor = '#000';
 	const sameShade = '#666';
-	const colorWithTransparency = 'rgba(102,102,102,0.5)';
+	const colorWithTransparency = 'rgba(102,102,102,0.5)'; // #666 with opacity.
 
 	beforeEach( () => {
 		speak.mockReset();
@@ -35,11 +36,25 @@ describe( 'ContrastChecker', () => {
 		expect( mount( <ContrastChecker /> ).html() ).toBeNull();
 	} );
 
+	test( 'should render null when no background or fallback background color is provided', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				textColor={ textColor }
+				linkColor={ linkColor }
+				isLargeText={ isLargeText }
+			/>
+		);
+
+		expect( speak ).not.toHaveBeenCalled();
+		expect( wrapper.html() ).toBeNull();
+	} );
+
 	test( 'should render null when the colors meet AA WCAG guidelines.', () => {
 		const wrapper = mount(
 			<ContrastChecker
 				backgroundColor={ backgroundColor }
 				textColor={ textColor }
+				linkColor={ linkColor }
 				isLargeText={ isLargeText }
 				fallbackBackgroundColor={ fallbackBackgroundColor }
 				fallbackTextColor={ fallbackTextColor }
@@ -50,11 +65,51 @@ describe( 'ContrastChecker', () => {
 		expect( wrapper.html() ).toBeNull();
 	} );
 
-	test( 'should render component when the colors do not meet AA WCAG guidelines.', () => {
+	test( 'should render component when the text and background colors do not meet AA WCAG guidelines.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ sameShade }
+				textColor={ sameShade }
+				isLargeText={ isLargeText }
+				fallbackBackgroundColor={ fallbackBackgroundColor }
+				fallbackTextColor={ fallbackTextColor }
+			/>
+		);
+
+		expect( speak ).toHaveBeenCalledWith(
+			'This color combination may be hard for people to read.'
+		);
+		expect( wrapper.find( Notice ).children().text() ).toBe(
+			'This color combination may be hard for people to read. Try using a brighter background color and/or a darker text color.'
+		);
+	} );
+
+	test( 'should render component when the link and background colors do not meet AA WCAG guidelines.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ sameShade }
+				textColor={ textColor }
+				linkColor={ sameShade }
+				isLargeText={ isLargeText }
+				fallbackBackgroundColor={ fallbackBackgroundColor }
+				fallbackTextColor={ fallbackTextColor }
+			/>
+		);
+
+		expect( speak ).toHaveBeenCalledWith(
+			'This color combination may be hard for people to read.'
+		);
+		expect( wrapper.find( Notice ).children().text() ).toBe(
+			'This color combination may be hard for people to read. Try using a brighter background color and/or a darker link color.'
+		);
+	} );
+
+	test( 'should render component when the link and text and background colors do not meet AA WCAG guidelines.', () => {
 		const wrapper = mount(
 			<ContrastChecker
 				backgroundColor={ sameShade }
 				textColor={ sameShade }
+				linkColor={ sameShade }
 				isLargeText={ isLargeText }
 				fallbackBackgroundColor={ fallbackBackgroundColor }
 				fallbackTextColor={ fallbackTextColor }
@@ -74,6 +129,7 @@ describe( 'ContrastChecker', () => {
 			<ContrastChecker
 				backgroundColor={ colorWithTransparency }
 				textColor={ sameShade }
+				linkColor={ sameShade }
 				isLargeText={ isLargeText }
 				fallbackBackgroundColor={ fallbackBackgroundColor }
 				fallbackTextColor={ fallbackTextColor }
@@ -99,6 +155,22 @@ describe( 'ContrastChecker', () => {
 		expect( wrapper.html() ).toBeNull();
 	} );
 
+	test( 'should render render null if link color contains a transparency', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ backgroundColor }
+				textColor={ textColor }
+				linkColor={ colorWithTransparency }
+				isLargeText={ isLargeText }
+				fallbackBackgroundColor={ fallbackBackgroundColor }
+				fallbackTextColor={ fallbackTextColor }
+			/>
+		);
+
+		expect( speak ).not.toHaveBeenCalled();
+		expect( wrapper.html() ).toBeNull();
+	} );
+
 	test( 'should render different message matching snapshot when background color has less brightness than text color.', () => {
 		const darkerShade = '#555';
 
@@ -233,6 +305,22 @@ describe( 'ContrastChecker', () => {
 		);
 	} );
 
+	test( 'should render messages when the linkColor is valid, but the fallback backgroundColor conflicts.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				linkColor={ linkColor }
+				fallbackBackgroundColor={ linkColor }
+			/>
+		);
+
+		expect( speak ).toHaveBeenCalledWith(
+			'This color combination may be hard for people to read.'
+		);
+		expect( wrapper.find( Notice ).children().text() ).toBe(
+			'This color combination may be hard for people to read. Try using a brighter background color and/or a darker link color.'
+		);
+	} );
+
 	test( 'should re-announce if colors change, but still insufficient contrast', () => {
 		const appRoot = document.createElement( 'div' );
 
@@ -258,4 +346,150 @@ describe( 'ContrastChecker', () => {
 
 		expect( speak ).toHaveBeenCalledTimes( 2 );
 	} );
+
+	// enableAlphaChecker tests
+	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 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)' }
+				linkColor={ linkColor }
+				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 component when the colors meet AA WCAG guidelines but the link color only has alpha transparency with alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ backgroundColor }
+				linkColor={ 'rgba(0,0,0,0.9)' }
+				textColor={ textColor }
+				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 }
+				linkColor={ linkColor }
+				isLargeText={ isLargeText }
+				enableAlphaChecker={ true }
+			/>
+		);
+
+		expect( speak ).not.toHaveBeenCalled();
+		expect( wrapper.html() ).toBeNull();
+	} );
+
+	test( 'should render null if background color contains a transparency with alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ colorWithTransparency }
+				textColor={ sameShade }
+				linkColor={ sameShade }
+				isLargeText={ isLargeText }
+				fallbackBackgroundColor={ fallbackBackgroundColor }
+				fallbackTextColor={ fallbackTextColor }
+				enableAlphaChecker={ true }
+			/>
+		);
+
+		expect( speak ).not.toHaveBeenCalled();
+		expect( wrapper.html() ).toBeNull();
+	} );
+
+	test( 'should render transparency warning only if one text is not readable but the other is transparent and the background color contains a transparency with alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ colorWithTransparency }
+				textColor={ sameShade }
+				linkColor={ 'rgba(0,0,0,0.9)' }
+				isLargeText={ isLargeText }
+				fallbackBackgroundColor={ fallbackBackgroundColor }
+				fallbackTextColor={ fallbackTextColor }
+				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 component and prioritize contrast warning when the colors do no meet AA WCAG guidelines and text has alpha transparency with the alpha checker enabled.', () => {
+		const wrapper = mount(
+			<ContrastChecker
+				backgroundColor={ sameShade }
+				textColor={ 'rgba(0,0,0,0.9)' }
+				linkColor={ sameShade }
+				isLargeText={ isLargeText }
+				fallbackBackgroundColor={ fallbackBackgroundColor }
+				fallbackTextColor={ fallbackTextColor }
+				enableAlphaChecker={ true }
+			/>
+		);
+
+		expect( speak ).toHaveBeenCalledWith(
+			'This color combination may be hard for people to read.'
+		);
+		expect( wrapper.find( Notice ).children().text() ).toBe(
+			'This color combination may be hard for people to read. Try using a brighter background color and/or a darker link color.'
+		);
+	} );
+
+	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)' }
+				linkColor={ 'rgba(0,0,0,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.'
+		);
+	} );
 } );