Image block: Add "Mark as decorative" toggle for accessibility

docs/reference-guides/core-blocks.md

@@ -445,7 +445,7 @@ Insert an image to make a visual statement. ([Source](https://github.com/WordPre
 -	**Name:** core/image
 -	**Category:** media
 -	**Supports:** align (center, full, left, right, wide), anchor, color (~~background~~, ~~text~~), filter (duotone), interactivity, shadow, spacing (margin)
--	**Attributes:** alt, aspectRatio, blob, caption, focalPoint, height, href, id, lightbox, linkClass, linkDestination, linkTarget, rel, scale, sizeSlug, title, url, width
+-	**Attributes:** alt, aspectRatio, blob, caption, focalPoint, height, href, id, isDecorative, lightbox, linkClass, linkDestination, linkTarget, rel, scale, sizeSlug, title, url, width
 
 ## Latest Comments
 

packages/block-library/src/image/block.json

@@ -105,6 +105,10 @@
 			"source": "attribute",
 			"selector": "figure > a",
 			"attribute": "target"
+		},
+		"isDecorative": {
+			"type": "boolean",
+			"default": false
 		}
 	},
 	"supports": {

packages/block-library/src/image/image.js

@@ -9,8 +9,10 @@ import {
 	Spinner,
 	TextareaControl,
 	TextControl,
+	CheckboxControl,
 	ToolbarButton,
 	ToolbarGroup,
+	__experimentalConfirmDialog as ConfirmDialog,
 	__experimentalToolsPanel as ToolsPanel,
 	__experimentalToolsPanelItem as ToolsPanelItem,
 	__experimentalUseCustomUnits as useCustomUnits,
@@ -29,6 +31,7 @@ import { useSelect, useDispatch } from '@wordpress/data';
 import {
 	BlockControls,
 	InspectorControls,
+	RichText,
 	__experimentalImageURLInputUI as ImageURLInputUI,
 	MediaReplaceFlow,
 	store as blockEditorStore,
@@ -261,6 +264,26 @@ function ContentOnlyControls( {
 	);
 }
 
+function getAltHelp( { lockAltControls, lockAltControlsMessage } ) {
+	if ( lockAltControls ) {
+		return <>{ lockAltControlsMessage }</>;
+	}
+	return (
+		<>
+			<ExternalLink
+				href={
+					// translators: Localized tutorial, if one exists. W3C Web Accessibility Initiative link has list of existing translations.
+					__(
+						'https://www.w3.org/WAI/tutorials/images/decision-tree/'
+					)
+				}
+			>
+				{ __( 'Describe the purpose of the image.' ) }
+			</ExternalLink>
+		</>
+	);
+}
+
 export default function Image( {
 	temporaryURL,
 	isSideloading,
@@ -297,6 +320,8 @@ export default function Image( {
 		sizeSlug,
 		lightbox,
 		metadata,
+		isDecorative,
+		caption,
 	} = attributes;
 	const [ imageElement, setImageElement ] = useState();
 	const [ resizeDelta, setResizeDelta ] = useState( null );
@@ -525,6 +550,7 @@ export default function Image( {
 		if ( enable && ! lightboxSetting?.enabled ) {
 			setAttributes( {
 				lightbox: { enabled: true },
+				isDecorative: false,
 			} );
 		} else if ( ! enable && lightboxSetting?.enabled ) {
 			setAttributes( {
@@ -563,6 +589,34 @@ export default function Image( {
 		setAttributes( { alt: newAlt } );
 	}
 
+	const [ isDecorativeConfirmVisible, setIsDecorativeConfirmVisible ] =
+		useState( false );
+
+	function applyDecorative() {
+		setAttributes( {
+			isDecorative: true,
+			alt: '',
+			caption: undefined,
+			href: undefined,
+			linkDestination: undefined,
+			linkTarget: undefined,
+			rel: undefined,
+		} );
+	}
+
+	function updateIsDecorative( value ) {
+		if ( ! value ) {
+			setAttributes( { isDecorative: false } );
+			return;
+		}
+		const hasDataToLose = alt || ! RichText.isEmpty( caption ) || href;
+		if ( hasDataToLose ) {
+			setIsDecorativeConfirmVisible( true );
+		} else {
+			applyDecorative();
+		}
+	}
+
 	const imperativeFocalPointPreview = ( value ) => {
 		if ( imageElement ) {
 			imageElement.style.setProperty(
@@ -806,7 +860,8 @@ export default function Image( {
 		isSingleSelected &&
 		! isEditingImage &&
 		! lockHrefControls &&
-		! lockUrlControls;
+		! lockUrlControls &&
+		! isDecorative;
 
 	const showCoverControls =
 		isSingleSelected && canInsertCover && ! isContentOnlyMode;
@@ -914,7 +969,10 @@ export default function Image( {
 				<InspectorControls group="content">
 					<ToolsPanel
 						label={ __( 'Media' ) }
-						resetAll={ () => onSelectImage( undefined ) }
+						resetAll={ () => {
+							onSelectImage( undefined );
+							setAttributes( { isDecorative: false } );
+						} }
 						dropdownMenuProps={ dropdownMenuProps }
 					>
 						{ ! lockUrlControls && (
@@ -944,45 +1002,48 @@ export default function Image( {
 								/>
 							</ToolsPanelItem>
 						) }
-						<ToolsPanelItem
-							label={ __( 'Alternative text' ) }
-							isShownByDefault
-							hasValue={ () => !! alt }
-							onDeselect={ () =>
-								setAttributes( { alt: undefined } )
-							}
-						>
-							<TextareaControl
+						{ ! isDecorative && (
+							<ToolsPanelItem
 								label={ __( 'Alternative text' ) }
-								value={ alt || '' }
-								onChange={ updateAlt }
-								readOnly={ lockAltControls }
-								help={
-									lockAltControls ? (
-										<>{ lockAltControlsMessage }</>
-									) : (
-										<>
-											<ExternalLink
-												href={
-													// translators: Localized tutorial, if one exists. W3C Web Accessibility Initiative link has list of existing translations.
-													__(
-														'https://www.w3.org/WAI/tutorials/images/decision-tree/'
-													)
-												}
-											>
-												{ __(
-													'Describe the purpose of the image.'
-												) }
-											</ExternalLink>
-											<br />
-											{ __(
-												'Leave empty if decorative.'
-											) }
-										</>
-									)
+								isShownByDefault
+								hasValue={ () => !! alt }
+								onDeselect={ () =>
+									setAttributes( { alt: undefined } )
 								}
-							/>
-						</ToolsPanelItem>
+							>
+								<TextareaControl
+									label={ __( 'Alternative text' ) }
+									value={ alt || '' }
+									onChange={ updateAlt }
+									readOnly={ lockAltControls }
+									help={ getAltHelp( {
+										lockAltControls,
+										lockAltControlsMessage,
+									} ) }
+								/>
+							</ToolsPanelItem>
+						) }
+
+						{ ! lockAltControls && ! lightboxChecked && (
+							<ToolsPanelItem
+								label={ __( 'Mark as decorative' ) }
+								isShownByDefault
+								hasValue={ () => !! isDecorative }
+								onDeselect={ () =>
+									setAttributes( { isDecorative: false } )
+								}
+							>
+								<CheckboxControl
+									__nextHasNoMarginBottom
+									label={ __( 'Mark as decorative' ) }
+									checked={ !! isDecorative }
+									onChange={ updateIsDecorative }
+									help={ __(
+										'Hidden from assistive technologies.'
+									) }
+								/>
+							</ToolsPanelItem>
+						) }
 					</ToolsPanel>
 				</InspectorControls>
 			) }
@@ -1072,7 +1133,17 @@ export default function Image( {
 	const filename = getFilename( url );
 	let defaultedAlt;
 
-	if ( alt ) {
+	if ( isDecorative ) {
+		defaultedAlt = filename
+			? sprintf(
+					/* translators: %s: file name */
+					__(
+						'This image has been marked as decorative; its file name is %s'
+					),
+					filename
+			  )
+			: __( 'This image has been marked as decorative.' );
+	} else if ( alt ) {
 		defaultedAlt = alt;
 	} else if ( filename ) {
 		defaultedAlt = sprintf(
@@ -1327,18 +1398,37 @@ export default function Image( {
 			{ img }
 			{ resizableBox }
 
-			<Caption
-				attributes={ attributes }
-				setAttributes={ setAttributes }
-				isSelected={ isSingleSelected }
-				insertBlocksAfter={ insertBlocksAfter }
-				label={ __( 'Image caption text' ) }
-				showToolbarButton={
-					isSingleSelected &&
-					( hasNonContentControls || isContentOnlyMode ) &&
-					! hideCaptionControls
-				}
-			/>
+			{ ! isDecorative && (
+				<Caption
+					attributes={ attributes }
+					setAttributes={ setAttributes }
+					isSelected={ isSingleSelected }
+					insertBlocksAfter={ insertBlocksAfter }
+					label={ __( 'Image caption text' ) }
+					showToolbarButton={
+						isSingleSelected &&
+						( hasNonContentControls || isContentOnlyMode ) &&
+						! hideCaptionControls
+					}
+				/>
+			) }
+
+			{ isDecorativeConfirmVisible && (
+				<ConfirmDialog
+					isOpen
+					onConfirm={ () => {
+						setIsDecorativeConfirmVisible( false );
+						applyDecorative();
+					} }
+					onCancel={ () => setIsDecorativeConfirmVisible( false ) }
+					confirmButtonText={ __( 'Mark as decorative' ) }
+					size="medium"
+				>
+					{ __(
+						'Marking this image as decorative will remove any alt text, caption, and links. Continue?'
+					) }
+				</ConfirmDialog>
+			) }
 		</>
 	);
 }

packages/block-library/src/image/save.js

@@ -37,6 +37,7 @@ export default function save( { attributes } ) {
 		linkTarget,
 		sizeSlug,
 		title,
+		isDecorative,
 		metadata: { bindings = {} } = {},
 	} = attributes;
 
@@ -78,6 +79,7 @@ export default function save( { attributes } ) {
 				height,
 			} }
 			title={ title }
+			role={ isDecorative ? 'none' : undefined }
 		/>
 	);
 

test/integration/fixtures/blocks/core__gallery-with-caption.json

@@ -27,7 +27,8 @@
 					"caption": "",
 					"id": 1421,
 					"sizeSlug": "large",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			},
@@ -40,7 +41,8 @@
 					"caption": "",
 					"id": 1440,
 					"sizeSlug": "large",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			}

test/integration/fixtures/blocks/core__gallery.json

@@ -27,7 +27,8 @@
 					"caption": "",
 					"id": 1421,
 					"sizeSlug": "large",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			},
@@ -40,7 +41,8 @@
 					"caption": "",
 					"id": 1440,
 					"sizeSlug": "large",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			}

test/integration/fixtures/blocks/core__gallery__columns.json

@@ -27,7 +27,8 @@
 					"caption": "",
 					"id": 1421,
 					"sizeSlug": "large",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			},
@@ -40,7 +41,8 @@
 					"caption": "",
 					"id": 1440,
 					"sizeSlug": "large",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			}

test/integration/fixtures/blocks/core__gallery__deprecated-1.json

@@ -17,7 +17,8 @@
 					"url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==",
 					"alt": "title",
 					"caption": "",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			},
@@ -28,7 +29,8 @@
 					"url": "data:image/jpeg;base64,/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEAAD8A0s8g/9k=",
 					"alt": "title",
 					"caption": "",
-					"linkDestination": "none"
+					"linkDestination": "none",
+					"isDecorative": false
 				},
 				"innerBlocks": []
 			}