@wordpress/block-library 8.19.2 → 8.20.0

package/src/cover/edit/color-utils.js

@@ -0,0 +1,122 @@
+/**
+ * External dependencies
+ */
+import { colord, extend } from 'colord';
+import namesPlugin from 'colord/plugins/names';
+import { FastAverageColor } from 'fast-average-color';
+import memoize from 'memize';
+
+/**
+ * WordPress dependencies
+ */
+import { applyFilters } from '@wordpress/hooks';
+
+/**
+ * @typedef {import('colord').RgbaColor} RgbaColor
+ */
+
+extend( [ namesPlugin ] );
+
+/**
+ * Fallback color when the average color can't be computed. The image may be
+ * rendering as transparent, and most sites have a light color background.
+ */
+export const DEFAULT_BACKGROUND_COLOR = '#FFF';
+
+/**
+ * Default dim color specified in style.css.
+ */
+export const DEFAULT_OVERLAY_COLOR = '#000';
+
+/**
+ * Performs a Porter Duff composite source over operation on two rgba colors.
+ *
+ * @see {@link https://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcover}
+ *
+ * @param {RgbaColor} source Source color.
+ * @param {RgbaColor} dest   Destination color.
+ *
+ * @return {RgbaColor} Composite color.
+ */
+export function compositeSourceOver( source, dest ) {
+	return {
+		r: source.r * source.a + dest.r * dest.a * ( 1 - source.a ),
+		g: source.g * source.a + dest.g * dest.a * ( 1 - source.a ),
+		b: source.b * source.a + dest.b * dest.a * ( 1 - source.a ),
+		a: source.a + dest.a * ( 1 - source.a ),
+	};
+}
+
+/**
+ * Retrieves the FastAverageColor singleton.
+ *
+ * @return {FastAverageColor} The FastAverageColor singleton.
+ */
+export function retrieveFastAverageColor() {
+	if ( ! retrieveFastAverageColor.fastAverageColor ) {
+		retrieveFastAverageColor.fastAverageColor = new FastAverageColor();
+	}
+	return retrieveFastAverageColor.fastAverageColor;
+}
+
+/**
+ * Computes the average color of an image.
+ *
+ * @param {string} url The url of the image.
+ *
+ * @return {Promise<string>} Promise of an average color as a hex string.
+ */
+export const getMediaColor = memoize( async ( url ) => {
+	if ( ! url ) {
+		return DEFAULT_BACKGROUND_COLOR;
+	}
+
+	// making the default color rgb for compat with FAC
+	const { r, g, b, a } = colord( DEFAULT_BACKGROUND_COLOR ).toRgb();
+
+	try {
+		const imgCrossOrigin = applyFilters(
+			'media.crossOrigin',
+			undefined,
+			url
+		);
+		const color = await retrieveFastAverageColor().getColorAsync( url, {
+			// The default color is white, which is the color
+			// that is returned if there's an error.
+			// colord returns alpga 0-1, FAC needs 0-255
+			defaultColor: [ r, g, b, a * 255 ],
+			// Errors that come up don't reject the promise,
+			// so error logging has to be silenced
+			// with this option.
+			silent: process.env.NODE_ENV === 'production',
+			crossOrigin: imgCrossOrigin,
+		} );
+		return color.hex;
+	} catch ( error ) {
+		// If there's an error return the fallback color.
+		return DEFAULT_BACKGROUND_COLOR;
+	}
+} );
+
+/**
+ * Computes if the color combination of the overlay and background color is dark.
+ *
+ * @param {number} dimRatio        Opacity of the overlay between 0 and 100.
+ * @param {string} overlayColor    CSS color string for the overlay.
+ * @param {string} backgroundColor CSS color string for the background.
+ *
+ * @return {boolean} true if the color combination composite result is dark.
+ */
+export function compositeIsDark( dimRatio, overlayColor, backgroundColor ) {
+	// Opacity doesn't matter if you're overlaying the same color on top of itself.
+	// And background doesn't matter when overlay is fully opaque.
+	if ( overlayColor === backgroundColor || dimRatio === 100 ) {
+		return colord( overlayColor ).isDark();
+	}
+	const overlay = colord( overlayColor )
+		.alpha( dimRatio / 100 )
+		.toRgb();
+	const background = colord( backgroundColor ).toRgb();
+	const composite = compositeSourceOver( overlay, background );
+	return colord( composite ).isDark();
+}

package/src/cover/edit/index.js

@@ -2,8 +2,6 @@
  * External dependencies
  */
 import classnames from 'classnames';
-import { extend } from 'colord';
-import namesPlugin from 'colord/plugins/names';
 
 /**
  * WordPress dependencies
@@ -37,14 +35,17 @@ import {
 	isContentPositionCenter,
 	getPositionClassName,
 	mediaPosition,
-	getCoverIsDark,
 } from '../shared';
 import CoverInspectorControls from './inspector-controls';
 import CoverBlockControls from './block-controls';
 import CoverPlaceholder from './cover-placeholder';
 import ResizableCoverPopover from './resizable-cover-popover';
-
-extend( [ namesPlugin ] );
+import {
+	getMediaColor,
+	compositeIsDark,
+	DEFAULT_BACKGROUND_COLOR,
+	DEFAULT_OVERLAY_COLOR,
+} from './color-utils';
 
 function getInnerBlocksTemplate( attributes ) {
 	return [
@@ -83,6 +84,8 @@ function CoverEdit( {
 	const {
 		contentPosition,
 		id,
+		url: originalUrl,
+		backgroundType: originalBackgroundType,
 		useFeaturedImage,
 		dimRatio,
 		focalPoint,
@@ -95,6 +98,7 @@ function CoverEdit( {
 		allowedBlocks,
 		templateLock,
 		tagName: TagName = 'div',
+		isUserOverlayColor,
 	} = attributes;
 
 	const [ featuredImage ] = useEntityProp(
@@ -114,23 +118,34 @@ function CoverEdit( {
 	);
 	const mediaUrl = media?.source_url;
 
+	// User can change the featured image outside of the block, but we still
+	// need to update the block when that happens. This effect should only
+	// run when the featured image changes in that case. All other cases are
+	// handled in their respective callbacks.
 	useEffect( () => {
-		async function setIsDark() {
-			__unstableMarkNextChangeAsNotPersistent();
-			const isDarkSetting = await getCoverIsDark(
-				mediaUrl,
+		( async () => {
+			if ( ! useFeaturedImage ) {
+				return;
+			}
+
+			const averageBackgroundColor = await getMediaColor( mediaUrl );
+
+			let newOverlayColor = overlayColor.color;
+			if ( ! isUserOverlayColor ) {
+				newOverlayColor = averageBackgroundColor;
+				__unstableMarkNextChangeAsNotPersistent();
+				setOverlayColor( newOverlayColor );
+			}
+
+			const newIsDark = compositeIsDark(
 				dimRatio,
-				overlayColor.color
+				newOverlayColor,
+				averageBackgroundColor
 			);
-			setAttributes( {
-				isDark: isDarkSetting,
-			} );
-		}
-		if ( useFeaturedImage ) {
-			setIsDark();
-		}
-		// We only ever want to run this effect if the mediaUrl changes.
-		// All other changes to the isDark state are handled in the appropriate event handlers.
+			__unstableMarkNextChangeAsNotPersistent();
+			setAttributes( { isDark: newIsDark } );
+		} )();
+		// Disable reason: Update the block only when the featured image changes.
 		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ mediaUrl ] );
 
@@ -141,32 +156,62 @@ function CoverEdit( {
 	const url = useFeaturedImage
 		? mediaUrl
 		: // Ensure the url is not malformed due to sanitization through `wp_kses`.
-		  attributes.url?.replaceAll( '&', '&' );
+		  originalUrl?.replaceAll( '&', '&' );
 	const backgroundType = useFeaturedImage
 		? IMAGE_BACKGROUND_TYPE
-		: attributes.backgroundType;
+		: originalBackgroundType;
 
 	const { createErrorNotice } = useDispatch( noticesStore );
 	const { gradientClass, gradientValue } = __experimentalUseGradient();
-	const setMedia = attributesFromMedia( setAttributes, dimRatio );
 
 	const onSelectMedia = async ( newMedia ) => {
-		// Only pass the url to getCoverIsDark if the media is an image as video is not handled.
-		const newUrl = newMedia?.type === 'image' ? newMedia.url : undefined;
-		const isDarkSetting = await getCoverIsDark(
-			newUrl,
-			dimRatio,
-			overlayColor.color
+		const mediaAttributes = attributesFromMedia( newMedia );
+
+		const averageBackgroundColor = await getMediaColor(
+			newMedia?.type === IMAGE_BACKGROUND_TYPE ? newMedia?.url : undefined
+		);
+
+		let newOverlayColor = overlayColor.color;
+		if ( ! isUserOverlayColor ) {
+			newOverlayColor = averageBackgroundColor;
+			setOverlayColor( newOverlayColor );
+
+			// Make undo revert the next setAttributes and the previous setOverlayColor.
+			__unstableMarkNextChangeAsNotPersistent();
+		}
+
+		const newDimRatio = dimRatio === 100 ? 50 : dimRatio;
+		const newIsDark = compositeIsDark(
+			newDimRatio,
+			newOverlayColor,
+			averageBackgroundColor
 		);
-		setMedia( newMedia, isDarkSetting );
+
+		setAttributes( {
+			...mediaAttributes,
+			focalPoint: undefined,
+			useFeaturedImage: undefined,
+			dimRatio: newDimRatio,
+			isDark: newIsDark,
+		} );
 	};
 
-	const onClearMedia = async () => {
-		const isDarkSetting = await getCoverIsDark(
-			undefined,
+	const onClearMedia = () => {
+		let newOverlayColor = overlayColor.color;
+		if ( ! isUserOverlayColor ) {
+			newOverlayColor = DEFAULT_OVERLAY_COLOR;
+			setOverlayColor( undefined );
+
+			// Make undo revert the next setAttributes and the previous setOverlayColor.
+			__unstableMarkNextChangeAsNotPersistent();
+		}
+
+		const newIsDark = compositeIsDark(
 			dimRatio,
-			overlayColor.color
+			newOverlayColor,
+			DEFAULT_BACKGROUND_COLOR
 		);
+
 		setAttributes( {
 			url: undefined,
 			id: undefined,
@@ -174,39 +219,50 @@ function CoverEdit( {
 			focalPoint: undefined,
 			hasParallax: undefined,
 			isRepeated: undefined,
-			useFeaturedImage: false,
-			isDark: isDarkSetting,
+			useFeaturedImage: undefined,
+			isDark: newIsDark,
 		} );
 	};
 
-	const onSetOverlayColor = async ( colorValue ) => {
-		const isDarkSetting = await getCoverIsDark( url, dimRatio, colorValue );
-		setOverlayColor( colorValue );
+	const onSetOverlayColor = async ( newOverlayColor ) => {
+		const averageBackgroundColor = await getMediaColor( url );
+		const newIsDark = compositeIsDark(
+			dimRatio,
+			newOverlayColor,
+			averageBackgroundColor
+		);
+
+		setOverlayColor( newOverlayColor );
+
+		// Make undo revert the next setAttributes and the previous setOverlayColor.
 		__unstableMarkNextChangeAsNotPersistent();
+
 		setAttributes( {
-			isDark: isDarkSetting,
+			isUserOverlayColor: true,
+			isDark: newIsDark,
 		} );
 	};
 
 	const onUpdateDimRatio = async ( newDimRatio ) => {
-		const isDarkSetting = await getCoverIsDark(
-			url,
+		const averageBackgroundColor = await getMediaColor( url );
+		const newIsDark = compositeIsDark(
 			newDimRatio,
-			overlayColor.color
+			overlayColor.color,
+			averageBackgroundColor
 		);
 
 		setAttributes( {
 			dimRatio: newDimRatio,
-			isDark: isDarkSetting,
+			isDark: newIsDark,
 		} );
 	};
 
-	const isUploadingMedia = isTemporaryMedia( id, url );
-
 	const onUploadError = ( message ) => {
 		createErrorNotice( message, { type: 'snackbar' } );
 	};
 
+	const isUploadingMedia = isTemporaryMedia( id, url );
+
 	const isImageBackground = IMAGE_BACKGROUND_TYPE === backgroundType;
 	const isVideoBackground = VIDEO_BACKGROUND_TYPE === backgroundType;
 
@@ -285,18 +341,43 @@ function CoverEdit( {
 	};
 
 	const toggleUseFeaturedImage = async () => {
-		const isDarkSetting = await ( useFeaturedImage
-			? getCoverIsDark( undefined, dimRatio, overlayColor.color )
-			: getCoverIsDark( mediaUrl, dimRatio, overlayColor.color ) );
+		const newUseFeaturedImage = ! useFeaturedImage;
+
+		const averageBackgroundColor = newUseFeaturedImage
+			? await getMediaColor( mediaUrl )
+			: DEFAULT_BACKGROUND_COLOR;
+
+		const newOverlayColor = ! isUserOverlayColor
+			? averageBackgroundColor
+			: overlayColor.color;
+
+		if ( ! isUserOverlayColor ) {
+			if ( newUseFeaturedImage ) {
+				setOverlayColor( newOverlayColor );
+			} else {
+				setOverlayColor( undefined );
+			}
+
+			// Make undo revert the next setAttributes and the previous setOverlayColor.
+			__unstableMarkNextChangeAsNotPersistent();
+		}
+
+		const newDimRatio = dimRatio === 100 ? 50 : dimRatio;
+		const newIsDark = compositeIsDark(
+			newDimRatio,
+			newOverlayColor,
+			averageBackgroundColor
+		);
+
 		setAttributes( {
 			id: undefined,
 			url: undefined,
-			useFeaturedImage: ! useFeaturedImage,
-			dimRatio: dimRatio === 100 ? 50 : dimRatio,
+			useFeaturedImage: newUseFeaturedImage,
+			dimRatio: newDimRatio,
 			backgroundType: useFeaturedImage
 				? IMAGE_BACKGROUND_TYPE
 				: undefined,
-			isDark: isDarkSetting,
+			isDark: newIsDark,
 		} );
 	};
 

package/src/cover/edit/inspector-controls.js

@@ -149,7 +149,7 @@ export default function CoverInspectorControls( {
 			'The <header> element should represent introductory content, typically a group of introductory or navigational aids.'
 		),
 		main: __(
-			'The <main> element should be used for the primary content of your document only. '
+			'The <main> element should be used for the primary content of your document only.'
 		),
 		section: __(
 			"The <section> element should represent a standalone portion of the document that can't be better represented by another element."

package/src/cover/edit.native.js

@@ -207,8 +207,15 @@ const Cover = ( {
 
 	const onSelectMedia = ( media ) => {
 		setDidUploadFail( false );
-		const onSelect = attributesFromMedia( setAttributes, dimRatio );
-		onSelect( media );
+
+		const mediaAttributes = attributesFromMedia( media );
+		setAttributes( {
+			...mediaAttributes,
+			focalPoint: undefined,
+			useFeaturedImage: undefined,
+			dimRatio: dimRatio === 100 ? 50 : dimRatio,
+			isDark: undefined,
+		} );
 	};
 
 	const onMediaPressed = () => {

package/src/cover/shared.js

@@ -1,14 +1,7 @@
-/**
- * External dependencies
- */
-import { FastAverageColor } from 'fast-average-color';
-import { colord } from 'colord';
-
 /**
  * WordPress dependencies
  */
 import { getBlobTypeByURL, isBlobURL } from '@wordpress/blob';
-import { applyFilters } from '@wordpress/hooks';
 
 const POSITION_CLASSNAMES = {
 	'top left': 'is-position-top-left',
@@ -41,50 +34,47 @@ export function dimRatioToClass( ratio ) {
 		: 'has-background-dim-' + 10 * Math.round( ratio / 10 );
 }
 
-export function attributesFromMedia( setAttributes, dimRatio ) {
-	return ( media, isDark ) => {
-		if ( ! media || ! media.url ) {
-			setAttributes( { url: undefined, id: undefined, isDark } );
-			return;
-		}
+export function attributesFromMedia( media ) {
+	if ( ! media || ! media.url ) {
+		return {
+			url: undefined,
+			id: undefined,
+		};
+	}
 
-		if ( isBlobURL( media.url ) ) {
-			media.type = getBlobTypeByURL( media.url );
-		}
+	if ( isBlobURL( media.url ) ) {
+		media.type = getBlobTypeByURL( media.url );
+	}
 
-		let mediaType;
-		// For media selections originated from a file upload.
-		if ( media.media_type ) {
-			if ( media.media_type === IMAGE_BACKGROUND_TYPE ) {
-				mediaType = IMAGE_BACKGROUND_TYPE;
-			} else {
-				// only images and videos are accepted so if the media_type is not an image we can assume it is a video.
-				// Videos contain the media type of 'file' in the object returned from the rest api.
-				mediaType = VIDEO_BACKGROUND_TYPE;
-			}
+	let mediaType;
+	// For media selections originated from a file upload.
+	if ( media.media_type ) {
+		if ( media.media_type === IMAGE_BACKGROUND_TYPE ) {
+			mediaType = IMAGE_BACKGROUND_TYPE;
 		} else {
-			// For media selections originated from existing files in the media library.
-			if (
-				media.type !== IMAGE_BACKGROUND_TYPE &&
-				media.type !== VIDEO_BACKGROUND_TYPE
-			) {
-				return;
-			}
-			mediaType = media.type;
+			// only images and videos are accepted so if the media_type is not an image we can assume it is a video.
+			// Videos contain the media type of 'file' in the object returned from the rest api.
+			mediaType = VIDEO_BACKGROUND_TYPE;
 		}
+	} else {
+		// For media selections originated from existing files in the media library.
+		if (
+			media.type !== IMAGE_BACKGROUND_TYPE &&
+			media.type !== VIDEO_BACKGROUND_TYPE
+		) {
+			return;
+		}
+		mediaType = media.type;
+	}
 
-		setAttributes( {
-			isDark,
-			dimRatio: dimRatio === 100 ? 50 : dimRatio,
-			url: media.url,
-			id: media.id,
-			alt: media?.alt,
-			backgroundType: mediaType,
-			focalPoint: undefined,
-			...( mediaType === VIDEO_BACKGROUND_TYPE
-				? { hasParallax: undefined }
-				: {} ),
-		} );
+	return {
+		url: media.url,
+		id: media.id,
+		alt: media?.alt,
+		backgroundType: mediaType,
+		...( mediaType === VIDEO_BACKGROUND_TYPE
+			? { hasParallax: undefined }
+			: {} ),
 	};
 }
 
@@ -117,86 +107,3 @@ export function getPositionClassName( contentPosition ) {
 
 	return POSITION_CLASSNAMES[ contentPosition ];
 }
-
-/**
- * Performs a Porter Duff composite source over operation on two rgba colors.
- *
- * @see https://www.w3.org/TR/compositing-1/#porterduffcompositingoperators_srcover
- *
- * @param {import('colord').RgbaColor} source Source color.
- * @param {import('colord').RgbaColor} dest   Destination color.
- * @return {import('colord').RgbaColor} Composite color.
- */
-function compositeSourceOver( source, dest ) {
-	return {
-		r: source.r * source.a + dest.r * dest.a * ( 1 - source.a ),
-		g: source.g * source.a + dest.g * dest.a * ( 1 - source.a ),
-		b: source.b * source.a + dest.b * dest.a * ( 1 - source.a ),
-		a: source.a + dest.a * ( 1 - source.a ),
-	};
-}
-
-function retrieveFastAverageColor() {
-	if ( ! retrieveFastAverageColor.fastAverageColor ) {
-		retrieveFastAverageColor.fastAverageColor = new FastAverageColor();
-	}
-	return retrieveFastAverageColor.fastAverageColor;
-}
-
-/**
- * This method evaluates if the cover block's background is dark or not and this boolean
- * can then be applied to the relevant attribute to help ensure that text is visible by default.
- * This needs to be recalculated in all of the following Cover block scenarios:
- * - When an overlay image is added, changed or removed
- * - When the featured image is selected as the overlay image, or removed from the overlay
- * - When the overlay color is changed
- * - When the overlay color is removed
- * - When the dimRatio is changed
- *
- * See the comments below for more details about which aspects take priority when
- * calculating the relative darkness of the Cover.
- *
- * @param {string} url
- * @param {number} dimRatio
- * @param {string} overlayColor
- * @return {Promise<boolean>} True if cover should be considered to be dark.
- */
-export async function getCoverIsDark( url, dimRatio = 50, overlayColor ) {
-	const overlay = colord( overlayColor )
-		.alpha( dimRatio / 100 )
-		.toRgb();
-
-	if ( url ) {
-		try {
-			const imgCrossOrigin = applyFilters(
-				'media.crossOrigin',
-				undefined,
-				url
-			);
-			const {
-				value: [ r, g, b, a ],
-			} = await retrieveFastAverageColor().getColorAsync( url, {
-				// Previously the default color was white, but that changed
-				// in v6.0.0 so it has to be manually set now.
-				defaultColor: [ 255, 255, 255, 255 ],
-				// Errors that come up don't reject the promise, so error
-				// logging has to be silenced with this option.
-				silent: process.env.NODE_ENV === 'production',
-				crossOrigin: imgCrossOrigin,
-			} );
-			// FAC uses 0-255 for alpha, but colord expects 0-1.
-			const media = { r, g, b, a: a / 255 };
-			const composite = compositeSourceOver( overlay, media );
-			return colord( composite ).isDark();
-		} catch ( error ) {
-			// If there's an error, just assume the image is dark.
-			return true;
-		}
-	}
-
-	// Assume a white background because it isn't easy to get the actual
-	// parent background color.
-	const background = { r: 255, g: 255, b: 255, a: 1 };
-	const composite = compositeSourceOver( overlay, background );
-	return colord( composite ).isDark();
-}