Gallery: Add labels to img, figure and figcaption elements for access…

…ibility (#25560)

* Add labels to img, figure and figcaption elements to make captions more accessible

* change aria-label to aria-describedby

* Update packages/block-library/src/gallery/gallery-image.js

Co-authored-by: Zebulan Stanphill <zebulanstanphill@protonmail.com>

* Update packages/block-library/src/gallery/gallery-image.js

Co-authored-by: Zebulan Stanphill <zebulanstanphill@protonmail.com>

* Replace aria-describedby with conditional aria-label.

* Avoid caption repetition.

* Revert "Avoid caption repetition."

This reverts commit d72429a4849e42469c3fb5c33ea08a2149c70c0e.

* Add deprecation.

* Remove unnecessary Id.

Co-authored-by: Zebulan Stanphill <zebulanstanphill@protonmail.com>
Co-authored-by: tellthemachines <isabel@tellthemachines.com>

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

@@ -13,8 +13,166 @@ import { RichText } from '@wordpress/block-editor';
  * Internal dependencies
  */
 import { defaultColumnsNumber } from './shared';
+import {
+	LINK_DESTINATION_ATTACHMENT,
+	LINK_DESTINATION_MEDIA,
+} from './constants';
 
 const deprecated = [
+	{
+		attributes: {
+			images: {
+				type: 'array',
+				default: [],
+				source: 'query',
+				selector: '.blocks-gallery-item',
+				query: {
+					url: {
+						type: 'string',
+						source: 'attribute',
+						selector: 'img',
+						attribute: 'src',
+					},
+					fullUrl: {
+						type: 'string',
+						source: 'attribute',
+						selector: 'img',
+						attribute: 'data-full-url',
+					},
+					link: {
+						type: 'string',
+						source: 'attribute',
+						selector: 'img',
+						attribute: 'data-link',
+					},
+					alt: {
+						type: 'string',
+						source: 'attribute',
+						selector: 'img',
+						attribute: 'alt',
+						default: '',
+					},
+					id: {
+						type: 'string',
+						source: 'attribute',
+						selector: 'img',
+						attribute: 'data-id',
+					},
+					caption: {
+						type: 'string',
+						source: 'html',
+						selector: '.blocks-gallery-item__caption',
+					},
+				},
+			},
+			ids: {
+				type: 'array',
+				items: {
+					type: 'number',
+				},
+				default: [],
+			},
+			columns: {
+				type: 'number',
+				minimum: 1,
+				maximum: 8,
+			},
+			caption: {
+				type: 'string',
+				source: 'html',
+				selector: '.blocks-gallery-caption',
+			},
+			imageCrop: {
+				type: 'boolean',
+				default: true,
+			},
+			linkTo: {
+				type: 'string',
+			},
+			sizeSlug: {
+				type: 'string',
+				default: 'large',
+			},
+		},
+		save( { attributes } ) {
+			const {
+				images,
+				columns = defaultColumnsNumber( attributes ),
+				imageCrop,
+				caption,
+				linkTo,
+			} = attributes;
+
+			return (
+				<figure
+					className={ `columns-${ columns } ${
+						imageCrop ? 'is-cropped' : ''
+					}` }
+				>
+					<ul className="blocks-gallery-grid">
+						{ images.map( ( image ) => {
+							let href;
+
+							switch ( linkTo ) {
+								case LINK_DESTINATION_MEDIA:
+									href = image.fullUrl || image.url;
+									break;
+								case LINK_DESTINATION_ATTACHMENT:
+									href = image.link;
+									break;
+							}
+
+							const img = (
+								<img
+									src={ image.url }
+									alt={ image.alt }
+									data-id={ image.id }
+									data-full-url={ image.fullUrl }
+									data-link={ image.link }
+									className={
+										image.id
+											? `wp-image-${ image.id }`
+											: null
+									}
+								/>
+							);
+
+							return (
+								<li
+									key={ image.id || image.url }
+									className="blocks-gallery-item"
+								>
+									<figure>
+										{ href ? (
+											<a href={ href }>{ img }</a>
+										) : (
+											img
+										) }
+										{ ! RichText.isEmpty(
+											image.caption
+										) && (
+											<RichText.Content
+												tagName="figcaption"
+												className="blocks-gallery-item__caption"
+												value={ image.caption }
+											/>
+										) }
+									</figure>
+								</li>
+							);
+						} ) }
+					</ul>
+					{ ! RichText.isEmpty( caption ) && (
+						<RichText.Content
+							tagName="figcaption"
+							className="blocks-gallery-caption"
+							value={ caption }
+						/>
+					) }
+				</figure>
+			);
+		},
+	},
 	{
 		attributes: {
 			images: {

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

@@ -39,6 +39,11 @@ export default function save( { attributes } ) {
 							href = image.link;
 							break;
 					}
+					// The image should only have an aria-label if it's within a link and has no alt text.
+					const imageLabel =
+						! image.alt && image.caption && href
+							? image.caption
+							: null;
 
 					const img = (
 						<img
@@ -50,6 +55,7 @@ export default function save( { attributes } ) {
 							className={
 								image.id ? `wp-image-${ image.id }` : null
 							}
+							aria-label={ imageLabel || null }
 						/>
 					);