Block API: Refactor the parser module in preparation for further work

packages/blocks/README.md

@@ -614,7 +614,7 @@ _Parameters_
 
 _Returns_
 
--   `Array`: Block list.
+-   `WPBlock[]`: Block list.
 
 ### parseWithAttributeSchema
 

packages/blocks/src/api/parser/apply-block-deprecated-versions.js

@@ -22,7 +22,7 @@ function stubFalse() {
  * and no eligible migrations exist.
  *
  * @param {import(".").WPBlock}                   block     Parsed and invalid block object.
- * @param {import(".").WPRawBlock}                rawBlock  Raw block object.
+ * @param {import(".").BlockNode}                 rawBlock  Raw block object.
  * @param {import('../registration').WPBlockType} blockType Block type. This is normalize not necessary and
  *                                                          can be inferred from the block name,
  *                                                          but it's here for performance reasons.

packages/blocks/src/api/parser/convert-legacy-block.js

@@ -3,29 +3,28 @@
  * both in the parser level for previous content and to convert such blocks
  * used in Custom Post Types templates.
  *
- * @param {string} name       The block's name
- * @param {Object} attributes The block's attributes
+ * @param {string|null} name       The block's name
+ * @param {Object|null} attributes The block's attributes
  *
- * @return {[string, Object]} The block's name and attributes, changed accordingly if a match was found
+ * @return {[string, Object|null]} The block's name and attributes, changed accordingly if a match was found
  */
 export function convertLegacyBlockNameAndAttributes( name, attributes ) {
-	const newAttributes = { ...attributes };
 	// Convert 'core/cover-image' block in existing content to 'core/cover'.
 	if ( 'core/cover-image' === name ) {
-		name = 'core/cover';
+		return [ 'core/cover', attributes ];
 	}
 
 	// Convert 'core/text' blocks in existing content to 'core/paragraph'.
 	if ( 'core/text' === name || 'core/cover-text' === name ) {
-		name = 'core/paragraph';
+		return [ 'core/paragraph', attributes ];
 	}
 
 	// Convert derivative blocks such as 'core/social-link-wordpress' to the
 	// canonical form 'core/social-link'.
 	if ( name && name.indexOf( 'core/social-link-' ) === 0 ) {
 		// Capture `social-link-wordpress` into `{"service":"wordpress"}`
-		newAttributes.service = name.substring( 17 );
-		name = 'core/social-link';
+		const service = name.substring( 17 );
+		return [ 'core/social-link', { ...attributes, service } ];
 	}
 
 	// Convert derivative blocks such as 'core-embed/instagram' to the
@@ -37,45 +36,53 @@ export function convertLegacyBlockNameAndAttributes( name, attributes ) {
 			speaker: 'speaker-deck',
 			polldaddy: 'crowdsignal',
 		};
+
+		const newAttributes = {};
+
 		newAttributes.providerNameSlug =
 			providerSlug in deprecated
 				? deprecated[ providerSlug ]
 				: providerSlug;
+
 		// This is needed as the `responsive` attribute was passed
 		// in a different way before the refactoring to block variations.
 		if ( ! [ 'amazon-kindle', 'wordpress' ].includes( providerSlug ) ) {
 			newAttributes.responsive = true;
 		}
-		name = 'core/embed';
+
+		return [ 'core/embed', { ...attributes, ...newAttributes } ];
 	}
 
 	// Convert Post Comment blocks in existing content to Comment blocks.
 	// TODO: Remove these checks when WordPress 6.0 is released.
 	if ( name === 'core/post-comment-author' ) {
-		name = 'core/comment-author-name';
+		return [ 'core/comment-author-name', attributes ];
 	}
 	if ( name === 'core/post-comment-content' ) {
-		name = 'core/comment-content';
+		return [ 'core/comment-content', attributes ];
 	}
 	if ( name === 'core/post-comment-date' ) {
-		name = 'core/comment-date';
+		return [ 'core/comment-date', attributes ];
 	}
 	if ( name === 'core/comments-query-loop' ) {
-		name = 'core/comments';
-		const { className = '' } = newAttributes;
-		if ( ! className.includes( 'wp-block-comments-query-loop' ) ) {
-			newAttributes.className = [
-				'wp-block-comments-query-loop',
-				className,
-			].join( ' ' );
-		}
+		const { className = '' } = attributes;
+		const needsClassName = ! className.includes(
+			'wp-block-comments-query-loop'
+		);
+		const newAttributes = needsClassName
+			? {
+					...attributes,
+					className: `wp-block-comments-query-loop ${ className }`,
+			  }
+			: attributes;
+
 		// Note that we also had to add a deprecation to the block in order
 		// for the ID change to work.
+		return [ 'core/comments', newAttributes ];
 	}
 	if ( name === 'core/post-comments' ) {
-		name = 'core/comments';
-		newAttributes.legacy = true;
+		return [ 'core/comments', { ...attributes, legacy: true } ];
 	}
 
-	return [ name, newAttributes ];
+	return [ name, attributes ];
 }