Add aria-describedby if image has no alt but has caption

packages/block-library/src/gallery/test/__snapshots__/index.native.js.snap

@@ -121,7 +121,7 @@ exports[`Gallery block sets caption to gallery 1`] = `
 exports[`Gallery block sets caption to gallery items 1`] = `
 "<!-- wp:gallery {"linkTo":"none"} -->
 <figure class="wp-block-gallery has-nested-images columns-default is-cropped"><!-- wp:image {"id":2000} -->
-<figure class="wp-block-image"><img src="https://test-site.files.wordpress.com/local-image-1.jpeg" alt="" class="wp-image-2000"/><figcaption class="wp-element-caption"><strong>Bold</strong> <em>italic</em> <s>strikethrough</s> image caption</figcaption></figure>
+<figure class="wp-block-image"><img src="https://test-site.files.wordpress.com/local-image-1.jpeg" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3k353j3k1d3j393k351e36393c353j1e3n3f3i343g3i353j3j1e333f3d1f3c3f33313c1d393d3137351d1h1e3a3g3537" class="wp-image-2000"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3k353j3k1d3j393k351e36393c353j1e3n3f3i343g3i353j3j1e333f3d1f3c3f33313c1d393d3137351d1h1e3a3g3537"><strong>Bold</strong> <em>italic</em> <s>strikethrough</s> image caption</figcaption></figure>
 <!-- /wp:image --></figure>
 <!-- /wp:gallery -->"
 `;

packages/block-library/src/gallery/test/__snapshots__/transforms.native.js.snap

@@ -5,15 +5,15 @@ exports[`Gallery block transformations to Columns block 1`] = `
 <div class="wp-block-columns"><!-- wp:column {"width":"100%"} -->
 <div class="wp-block-column" style="flex-basis:100%"><!-- wp:gallery {"columns":8,"linkTo":"none","className":"alignfull"} -->
 <figure class="wp-block-gallery has-nested-images columns-8 is-cropped alignfull"><!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon.png" alt=""/><figcaption class="wp-element-caption">Paragraph</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1e3g3e37">Paragraph</figcaption></figure>
 <!-- /wp:image -->
 
 <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Heading.png" alt=""/><figcaption class="wp-element-caption">Heading</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Heading.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d28353134393e371e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d28353134393e371e3g3e37">Heading</figcaption></figure>
 <!-- /wp:image -->
 
 <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Subheading.png" alt=""/><figcaption class="wp-element-caption">Subheading</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Subheading.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d2j3l3238353134393e371e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d2j3l3238353134393e371e3g3e37">Subheading</figcaption></figure>
 <!-- /wp:image --></figure>
 <!-- /wp:gallery --></div>
 <!-- /wp:column --></div>
@@ -24,30 +24,30 @@ exports[`Gallery block transformations to Group block 1`] = `
 "<!-- wp:group {"layout":{"type":"constrained"}} -->
 <div class="wp-block-group"><!-- wp:gallery {"columns":8,"linkTo":"none","className":"alignfull"} -->
 <figure class="wp-block-gallery has-nested-images columns-8 is-cropped alignfull"><!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon.png" alt=""/><figcaption class="wp-element-caption">Paragraph</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1e3g3e37">Paragraph</figcaption></figure>
 <!-- /wp:image -->
 
 <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Heading.png" alt=""/><figcaption class="wp-element-caption">Heading</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Heading.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d28353134393e371e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d28353134393e371e3g3e37">Heading</figcaption></figure>
 <!-- /wp:image -->
 
 <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Subheading.png" alt=""/><figcaption class="wp-element-caption">Subheading</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Subheading.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d2j3l3238353134393e371e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d2j3l3238353134393e371e3g3e37">Subheading</figcaption></figure>
 <!-- /wp:image --></figure>
 <!-- /wp:gallery --></div>
 <!-- /wp:group -->"
 `;
 
 exports[`Gallery block transformations to Image block 1`] = `
 "<!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon.png" alt=""/><figcaption class="wp-element-caption">Paragraph</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1e3g3e37">Paragraph</figcaption></figure>
 <!-- /wp:image -->
 
 <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Heading.png" alt=""/><figcaption class="wp-element-caption">Heading</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Heading.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d28353134393e371e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d28353134393e371e3g3e37">Heading</figcaption></figure>
 <!-- /wp:image -->
 
 <!-- wp:image {"sizeSlug":"large","linkDestination":"none"} -->
-<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Subheading.png" alt=""/><figcaption class="wp-element-caption">Subheading</figcaption></figure>
+<figure class="wp-block-image size-large"><img src="https://wordpress.org/gutenberg/files/2018/07/Block-Icon-Subheading.png" alt="" aria-describedby="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d2j3l3238353134393e371e3g3e37"/><figcaption class="wp-element-caption" id="wp-image-caption-383k3k3g3j1q1f1f3n3f3i343g3i353j3j1e3f3i371f373l3k353e32353i371f36393c353j1f1i1g1h1o1f1g1n1f223c3f333b1d29333f3e1d2j3l3238353134393e371e3g3e37">Subheading</figcaption></figure>
 <!-- /wp:image -->"
 `;

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

@@ -6,7 +6,12 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { RichText, useBlockProps } from '@wordpress/block-editor';
+import {
+	RichText,
+	useBlockProps,
+	__experimentalGetElementClassName,
+	__experimentalGetBorderClassesAndStyles as getBorderClassesAndStyles,
+} from '@wordpress/block-editor';
 
 const blockAttributes = {
 	align: {
@@ -93,6 +98,183 @@ const blockSupports = {
 };
 
 const deprecated = [
+	// Deprecate the version that does not use the caption to describe the image
+	// when the image has a caption but no alt text.
+	{
+		attributes: {
+			align: {
+				type: 'string',
+			},
+			url: {
+				type: 'string',
+				source: 'attribute',
+				selector: 'img',
+				attribute: 'src',
+				__experimentalRole: 'content',
+			},
+			alt: {
+				type: 'string',
+				source: 'attribute',
+				selector: 'img',
+				attribute: 'alt',
+				default: '',
+				__experimentalRole: 'content',
+			},
+			caption: {
+				type: 'string',
+				source: 'html',
+				selector: 'figcaption',
+				__experimentalRole: 'content',
+			},
+			title: {
+				type: 'string',
+				source: 'attribute',
+				selector: 'img',
+				attribute: 'title',
+				__experimentalRole: 'content',
+			},
+			href: {
+				type: 'string',
+				source: 'attribute',
+				selector: 'figure > a',
+				attribute: 'href',
+				__experimentalRole: 'content',
+			},
+			rel: {
+				type: 'string',
+				source: 'attribute',
+				selector: 'figure > a',
+				attribute: 'rel',
+			},
+			linkClass: {
+				type: 'string',
+				source: 'attribute',
+				selector: 'figure > a',
+				attribute: 'class',
+			},
+			id: {
+				type: 'number',
+				__experimentalRole: 'content',
+			},
+			width: {
+				type: 'number',
+			},
+			height: {
+				type: 'number',
+			},
+			sizeSlug: {
+				type: 'string',
+			},
+			linkDestination: {
+				type: 'string',
+			},
+			linkTarget: {
+				type: 'string',
+				source: 'attribute',
+				selector: 'figure > a',
+				attribute: 'target',
+			},
+		},
+		supports: {
+			anchor: true,
+			color: {
+				text: false,
+				background: false,
+			},
+			filter: {
+				duotone: true,
+			},
+			__experimentalBorder: {
+				color: true,
+				radius: true,
+				width: true,
+				__experimentalSelector: 'img, .wp-block-image__crop-area',
+				__experimentalSkipSerialization: true,
+				__experimentalDefaultControls: {
+					color: true,
+					radius: true,
+					width: true,
+				},
+			},
+		},
+		save( { attributes } ) {
+			const {
+				url,
+				alt,
+				caption,
+				align,
+				href,
+				rel,
+				linkClass,
+				width,
+				height,
+				id,
+				linkTarget,
+				sizeSlug,
+				title,
+			} = attributes;
+
+			const newRel = ! rel ? undefined : rel;
+			const borderProps = getBorderClassesAndStyles( attributes );
+
+			const classes = classnames( {
+				[ `align${ align }` ]: align,
+				[ `size-${ sizeSlug }` ]: sizeSlug,
+				'is-resized': width || height,
+				'has-custom-border':
+					!! borderProps.className ||
+					( borderProps.style &&
+						Object.keys( borderProps.style ).length > 0 ),
+			} );
+
+			const imageClasses = classnames( borderProps.className, {
+				[ `wp-image-${ id }` ]: !! id,
+			} );
+
+			const image = (
+				<img
+					src={ url }
+					alt={ alt }
+					className={ imageClasses || undefined }
+					style={ borderProps.style }
+					width={ width }
+					height={ height }
+					title={ title }
+				/>
+			);
+
+			const figure = (
+				<>
+					{ href ? (
+						<a
+							className={ linkClass }
+							href={ href }
+							target={ linkTarget }
+							rel={ newRel }
+						>
+							{ image }
+						</a>
+					) : (
+						image
+					) }
+					{ ! RichText.isEmpty( caption ) && (
+						<RichText.Content
+							className={ __experimentalGetElementClassName(
+								'caption'
+							) }
+							tagName="figcaption"
+							value={ caption }
+						/>
+					) }
+				</>
+			);
+			return (
+				<figure { ...useBlockProps.save( { className: classes } ) }>
+					{ figure }
+				</figure>
+			);
+		},
+	},
 	// The following deprecation moves existing border radius styles onto the
 	// inner img element where new border block support styles must be applied.
 	// It will also add a new `.has-custom-border` class for existing blocks

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

@@ -325,6 +325,19 @@ export default function Image( {
 		);
 	}
 
+	let describedById = 'wp-image-caption';
+	if ( url ) {
+		// Use the hashed url to create an ID to use with aria-describedby.
+		const hashString = ( str ) =>
+			str
+				.split( '' )
+				.map( ( c ) =>
+					c.charCodeAt( 0 ).toString( 32 ).padStart( 2, '0' )
+				)
+				.join( '' );
+		describedById = `wp-image-caption-${ hashString( url ) }`;
+	}
+
 	const controls = (
 		<>
 			<BlockControls group="block">
@@ -487,6 +500,11 @@ export default function Image( {
 			<img
 				src={ temporaryURL || url }
 				alt={ defaultedAlt }
+				aria-describedby={
+					! alt && ! RichText.isEmpty( caption ) && ! href
+						? describedById
+						: undefined
+				}
 				onError={ () => onImageError() }
 				onLoad={ ( event ) => {
 					setLoadedNaturalSize( {
@@ -637,6 +655,11 @@ export default function Image( {
 						aria-label={ __( 'Image caption text' ) }
 						placeholder={ __( 'Add caption' ) }
 						value={ caption }
+						id={
+							! alt && ! RichText.isEmpty( caption )
+								? describedById
+								: undefined
+						}
 						onChange={ ( value ) =>
 							setAttributes( { caption: value } )
 						}

packages/block-library/src/image/index.php

@@ -11,7 +11,7 @@
  *
  * @param  array  $attributes The block attributes.
  * @param  string $content    The block content.
- * @return string Returns the block content with the data-id attribute added.
+ * @return string Returns the block content with the data-id attribute and aria-describedby added.
  */
 function render_block_core_image( $attributes, $content ) {
 
@@ -22,12 +22,43 @@ function render_block_core_image( $attributes, $content ) {
 		return '';
 	}
 
+	// Check if the image block has an alternative text.
+	$find_alt_attribute = new WP_HTML_Tag_Processor( $content );
+	$find_alt_attribute->next_tag( array( 'tag_name' => 'img' ) );
+	$alt = $find_alt_attribute->get_attribute( 'alt' ) ? $find_alt_attribute->get_attribute( 'alt' ) : '';
+
+	// If an image block has no alternative text but has a caption,
+	// and aria-describedby is not set, add aria-describedby to the image or image link.
+	if ( empty( $alt ) &&
+		str_contains( $content, 'wp-element-caption' ) &&
+		! str_contains( $content, 'aria-describedby' )
+	) {
+		$unique_id         = wp_unique_id( 'wp-image-caption-' );
+		$processed_content = new WP_HTML_Tag_Processor( $content );
+		if ( str_contains( $content, 'href' ) ) {
+			$processed_content->next_tag( array( 'tag_name' => 'a' ) );
+			$processed_content->set_attribute( 'aria-describedby', $unique_id );
+		} else {
+			$processed_content->next_tag( array( 'tag_name' => 'img' ) );
+			$processed_content->set_attribute( 'aria-describedby', $unique_id );
+		}
+		$processed_content->next_tag(
+			array(
+				'tag_name'   => 'figcaption',
+				'class_name' => 'wp-element-caption',
+			)
+		);
+		$processed_content->set_attribute( 'id', $unique_id );
+		$content = $processed_content->get_updated_html();
+	}
+
 	if ( isset( $attributes['data-id'] ) ) {
 		// Add the data-id="$id" attribute to the img element
 		// to provide backwards compatibility for the Gallery Block,
 		// which now wraps Image Blocks within innerBlocks.
 		// The data-id attribute is added in a core/gallery `render_block_data` hook.
 		$processor->set_attribute( 'data-id', $attributes['data-id'] );
+		$content = $processor->get_updated_html();
 	}
 
 	$link_destination = isset( $attributes['linkDestination'] ) ? $attributes['linkDestination'] : 'none';
@@ -102,7 +133,7 @@ function render_block_core_image( $attributes, $content ) {
 HTML;
 	}
 
-	return $processor->get_updated_html();
+	return $content;
 }
 
 /**