WIP: Add descriptions to register_block_pattern. (#23070)

Co-authored-by: Carolina Nymark <hi@themesbycarolina.com>

docs/designers-developers/developers/block-api/block-patterns.md

@@ -15,16 +15,19 @@ The `register_block_pattern` function receives the name of the pattern as the fi
 The properties of the pattern include:
  - `title` (required): A human-readable title for the pattern.
  - `content` (required): Raw HTML content for the pattern.
+ - `description`: A visually hidden text used to describe the pattern in the inserter. A description is optional but it is strongly encouraged when the title does not fully describe what the pattern does.
  - `categories`: A list of pattern categories used to group patterns. Patterns can be shown on multiple categories.
  - `keywords`: Aliases or keywords that help users discover it while searching.
+ - `viewportWidth`: Specify the width of the pattern in the inserter.
 
 ```php
 register_block_pattern(
-    'my-plugin/my-awesome-pattern',
-    array(
-		'title'   => __( 'Two buttons', 'my-plugin' ),
-        'content' => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">" . esc_html__( 'Button One', 'my-plugin' ) . "</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">" . esc_html__( 'Button Two', 'my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
-    )
+	'my-plugin/my-awesome-pattern',
+	array(
+		'title'       => __( 'Two buttons', 'my-plugin' ),
+		'description' => _x( 'Two horizontal buttons, the left button is filled in, and the right button is outlined.', 'Block pattern description', 'my-plugin' ),
+		'content'     => "<!-- wp:buttons {\"align\":\"center\"} -->\n<div class=\"wp-block-buttons aligncenter\"><!-- wp:button {\"backgroundColor\":\"very-dark-gray\",\"borderRadius\":0} -->\n<div class=\"wp-block-button\"><a class=\"wp-block-button__link has-background has-very-dark-gray-background-color no-border-radius\">" . esc_html__( 'Button One', 'my-plugin' ) . "</a></div>\n<!-- /wp:button -->\n\n<!-- wp:button {\"textColor\":\"very-dark-gray\",\"borderRadius\":0,\"className\":\"is-style-outline\"} -->\n<div class=\"wp-block-button is-style-outline\"><a class=\"wp-block-button__link has-text-color has-very-dark-gray-color no-border-radius\">" . esc_html__( 'Button Two', 'my-plugin' ) . "</a></div>\n<!-- /wp:button --></div>\n<!-- /wp:buttons -->",
+	)
 );
 ```
 

lib/class-wp-block-patterns-registry.php

@@ -32,7 +32,7 @@ final class WP_Block_Patterns_Registry {
 	 * Registers a pattern.
 	 *
 	 * @param string $pattern_name       Pattern name including namespace.
-	 * @param array  $pattern_properties Array containing the properties of the pattern: label, content.
+	 * @param array  $pattern_properties Array containing the properties of the pattern: Title, content, description, viewportWidth, categories, keywords.
 	 * @return boolean True if the pattern was registered with success and false otherwise.
 	 */
 	public function register( $pattern_name, $pattern_properties ) {
@@ -42,6 +42,18 @@ public function register( $pattern_name, $pattern_properties ) {
 			return false;
 		}
 
+		if ( ! isset( $pattern_properties['title'] ) || ! is_string( $pattern_properties['title'] ) ) {
+			$message = __( 'Pattern title must be a string.', 'gutenberg' );
+			_doing_it_wrong( __METHOD__, $message, '8.5.0' );
+			return false;
+		}
+
+		if ( ! isset( $pattern_properties['content'] ) || ! is_string( $pattern_properties['content'] ) ) {
+			$message = __( 'Pattern content must be a string.', 'gutenberg' );
+			_doing_it_wrong( __METHOD__, $message, '8.5.0' );
+			return false;
+		}
+
 		$this->registered_patterns[ $pattern_name ] = array_merge(
 			$pattern_properties,
 			array( 'name' => $pattern_name )

lib/patterns/two-images.php

@@ -6,7 +6,8 @@
  */
 
 return array(
-	'title'      => __( 'Two images side by side', 'gutenberg' ),
-	'categories' => array( 'gallery' ),
-	'content'    => "<!-- wp:gallery {\"ids\":[null,null]} -->\n<figure class=\"wp-block-gallery columns-2 is-cropped\"><ul class=\"blocks-gallery-grid\"><li class=\"blocks-gallery-item\"><figure><img src=\"https://s.w.org/images/core/5.3/Glacial_lakes,_Bhutan.jpg\" alt=\"\" data-id=\"\"/></figure></li><li class=\"blocks-gallery-item\"><figure><img src=\"https://s.w.org/images/core/5.3/Sediment_off_the_Yucatan_Peninsula.jpg\" alt=\"\" data-id=\"\"/></figure></li></ul></figure>\n<!-- /wp:gallery -->",
+	'title'       => __( 'Two images side by side', 'gutenberg' ),
+	'categories'  => array( 'gallery' ),
+	'description' => _x( 'An image gallery with two cropped example images.', 'Block pattern description', 'gutenberg' ),
+	'content'     => "<!-- wp:gallery {\"ids\":[null,null]} -->\n<figure class=\"wp-block-gallery columns-2 is-cropped\"><ul class=\"blocks-gallery-grid\"><li class=\"blocks-gallery-item\"><figure><img src=\"https://s.w.org/images/core/5.3/Glacial_lakes,_Bhutan.jpg\" alt=\"\" data-id=\"\"/></figure></li><li class=\"blocks-gallery-item\"><figure><img src=\"https://s.w.org/images/core/5.3/Sediment_off_the_Yucatan_Peninsula.jpg\" alt=\"\" data-id=\"\"/></figure></li></ul></figure>\n<!-- /wp:gallery -->",
 );

packages/block-editor/src/components/block-patterns-list/index.js

@@ -4,6 +4,8 @@
 import { useMemo } from '@wordpress/element';
 import { parse } from '@wordpress/blocks';
 import { ENTER, SPACE } from '@wordpress/keycodes';
+import { VisuallyHidden } from '@wordpress/components';
+import { useInstanceId } from '@wordpress/compose';
 
 /**
  * Internal dependencies
@@ -13,6 +15,8 @@ import BlockPreview from '../block-preview';
 function BlockPattern( { pattern, onClick } ) {
 	const { content, viewportWidth } = pattern;
 	const blocks = useMemo( () => parse( content ), [ content ] );
+	const instanceId = useInstanceId( BlockPattern );
+	const descriptionId = `block-editor-block-patterns-list__item-description-${ instanceId }`;
 
 	return (
 		<div
@@ -26,11 +30,17 @@ function BlockPattern( { pattern, onClick } ) {
 			} }
 			tabIndex={ 0 }
 			aria-label={ pattern.title }
+			aria-describedby={ pattern.description ? descriptionId : undefined }
 		>
 			<BlockPreview blocks={ blocks } viewportWidth={ viewportWidth } />
 			<div className="block-editor-block-patterns-list__item-title">
 				{ pattern.title }
 			</div>
+			{ !! pattern.description && (
+				<VisuallyHidden id={ descriptionId }>
+					{ pattern.description }
+				</VisuallyHidden>
+			) }
 		</div>
 	);
 }