Blocks: Deprecate registerBlockTypeFromMetadata in favor of `regist…

…erBlockType` (#32030)

docs/how-to-guides/backward-compatibility/deprecations.md

@@ -2,6 +2,10 @@
 
 For features included in the Gutenberg plugin, the deprecation policy is intended to support backward compatibility for two minor plugin releases, when possible. Features and code included in a stable release of WordPress are not included in this deprecation timeline, and are instead subject to the [versioning policies of the WordPress project](https://make.wordpress.org/core/handbook/about/release-cycle/version-numbering/). The current deprecations are listed below and are grouped by _the version at which they will be removed completely_. If your plugin depends on these behaviors, you must update to the recommended alternative before the noted version.
 
+## 11.0.0
+
+-   `wp.blocks.registerBlockTypeFromMetadata` method has been removed. Use `wp.blocks.registerBlockType` method instead.
+
 ## 10.3.0
 
 -   Passing a tuple of components with `as` prop to `ActionItem.Slot` component is no longer supported. Please pass a component with `as` prop instead. Example:

docs/reference-guides/block-api/block-metadata.md

@@ -470,16 +470,16 @@ Implementation follows the existing [get_plugin_data](https://codex.wordpress.or
 
 ### JavaScript
 
-In JavaScript, you need to use `registerBlockTypeFromMetadata` method from `@wordpress/blocks` package to process loaded block metadata. All localized properties get automatically wrapped in `_x` (from `@wordpress/i18n` package) function calls similar to how it works in PHP.
+In JavaScript, you can use `registerBlockType` method from `@wordpress/blocks` package and pass the metadata object loaded from `block.json` as the first param. All localized properties get automatically wrapped in `_x` (from `@wordpress/i18n` package) function calls similar to how it works in PHP.
 
 **Example:**
 
 ```js
-import { registerBlockTypeFromMetadata } from '@wordpress/blocks';
+import { registerBlockType } from '@wordpress/blocks';
 import Edit from './edit';
 import metadata from './block.json';
 
-registerBlockTypeFromMetadata( metadata, {
+registerBlockType( metadata, {
 	edit: Edit,
 	// ...other client-side settings
 } );

packages/block-library/src/index.js

@@ -4,7 +4,7 @@
 import '@wordpress/core-data';
 import '@wordpress/block-editor';
 import {
-	registerBlockTypeFromMetadata,
+	registerBlockType,
 	setDefaultBlockName,
 	setFreeformContentHandlerName,
 	setUnregisteredTypeHandlerName,
@@ -105,7 +105,7 @@ const registerBlock = ( block ) => {
 		return;
 	}
 	const { metadata, settings, name } = block;
-	registerBlockTypeFromMetadata( { name, ...metadata }, settings );
+	registerBlockType( { name, ...metadata }, settings );
 };
 
 /**

packages/block-library/src/index.native.js

@@ -10,7 +10,6 @@ import { sortBy } from 'lodash';
 import {
 	hasBlockSupport,
 	registerBlockType,
-	registerBlockTypeFromMetadata,
 	setDefaultBlockName,
 	setFreeformContentHandlerName,
 	setUnregisteredTypeHandlerName,
@@ -128,7 +127,7 @@ const registerBlock = ( block ) => {
 		return;
 	}
 	const { metadata, settings, name } = block;
-	registerBlockTypeFromMetadata(
+	registerBlockType(
 		{
 			name,
 			...metadata,

packages/blocks/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### New API
+
+-   `registerBlockType` method can be used to register a block type using the metadata loaded from `block.json` file ([#32030](https://github.com/WordPress/gutenberg/pull/32030)).
+
+### Deprecations
+
+-   `registerBlockTypeFromMetadata` was deprecated in favor of `registerBlockType` that support now the same functionality ([#32030](https://github.com/WordPress/gutenberg/pull/32030)).
+
 ## 9.0.0 (2021-05-14)
 
 ### Breaking Changes

packages/blocks/README.md

@@ -706,7 +706,7 @@ editor interface where blocks are implemented.
 
 _Parameters_
 
--   _name_ `string`: Block name.
+-   _blockNameOrMetadata_ `string|Object`: Block type name or its metadata.
 -   _settings_ `Object`: Block settings.
 
 _Returns_
@@ -715,18 +715,13 @@ _Returns_
 
 <a name="registerBlockTypeFromMetadata" href="#registerBlockTypeFromMetadata">#</a> **registerBlockTypeFromMetadata**
 
-Registers a new block provided from metadata stored in `block.json` file.
-It uses `registerBlockType` internally.
+> **Deprecated** Use `registerBlockType` instead.
 
-_Related_
-
--   registerBlockType
+Registers a new block provided from metadata stored in `block.json` file.
 
 _Parameters_
 
 -   _metadata_ `Object`: Block metadata loaded from `block.json`.
--   _metadata.name_ `string`: Block name.
--   _metadata.textdomain_ `string`: Textdomain to use with translations.
 -   _additionalSettings_ `Object`: Additional block settings.
 
 _Returns_

packages/blocks/src/api/registration.js

@@ -22,6 +22,7 @@ import {
 /**
  * WordPress dependencies
  */
+import deprecated from '@wordpress/deprecated';
 import { applyFilters } from '@wordpress/hooks';
 import { select, dispatch } from '@wordpress/data';
 import { _x } from '@wordpress/i18n';
@@ -192,18 +193,77 @@ export function unstable__bootstrapServerSideBlockDefinitions( definitions ) {
 	}
 }
 
+/**
+ * Gets block settings from metadata loaded from `block.json` file.
+ *
+ * @param {Object} metadata            Block metadata loaded from `block.json`.
+ * @param {string} metadata.textdomain Textdomain to use with translations.
+ *
+ * @return {Object} Block settings.
+ */
+function getBlockSettingsFromMetadata( { textdomain, ...metadata } ) {
+	const allowedFields = [
+		'apiVersion',
+		'title',
+		'category',
+		'parent',
+		'icon',
+		'description',
+		'keywords',
+		'attributes',
+		'providesContext',
+		'usesContext',
+		'supports',
+		'styles',
+		'example',
+		'variations',
+	];
+
+	const settings = pick( metadata, allowedFields );
+
+	if ( textdomain ) {
+		Object.keys( i18nBlockSchema ).forEach( ( key ) => {
+			if ( ! settings[ key ] ) {
+				return;
+			}
+			settings[ key ] = translateBlockSettingUsingI18nSchema(
+				i18nBlockSchema[ key ],
+				settings[ key ],
+				textdomain
+			);
+		} );
+	}
+
+	return settings;
+}
+
 /**
  * Registers a new block provided a unique name and an object defining its
  * behavior. Once registered, the block is made available as an option to any
  * editor interface where blocks are implemented.
  *
- * @param {string} name     Block name.
- * @param {Object} settings Block settings.
+ * @param {string|Object} blockNameOrMetadata Block type name or its metadata.
+ * @param {Object}        settings            Block settings.
  *
  * @return {?WPBlock} The block, if it has been successfully registered;
  *                    otherwise `undefined`.
  */
-export function registerBlockType( name, settings ) {
+export function registerBlockType( blockNameOrMetadata, settings ) {
+	const name = isObject( blockNameOrMetadata )
+		? blockNameOrMetadata.name
+		: blockNameOrMetadata;
+
+	if ( typeof name !== 'string' ) {
+		console.error( 'Block names must be strings.' );
+		return;
+	}
+
+	if ( isObject( blockNameOrMetadata ) ) {
+		unstable__bootstrapServerSideBlockDefinitions( {
+			[ name ]: getBlockSettingsFromMetadata( blockNameOrMetadata ),
+		} );
+	}
+
 	settings = {
 		name,
 		icon: blockDefault,
@@ -218,10 +278,6 @@ export function registerBlockType( name, settings ) {
 		...settings,
 	};
 
-	if ( typeof name !== 'string' ) {
-		console.error( 'Block names must be strings.' );
-		return;
-	}
 	if ( ! /^[a-z][a-z0-9-]*\/[a-z][a-z0-9-]*$/.test( name ) ) {
 		console.error(
 			'Block names must contain a namespace prefix, include only lowercase alphanumeric characters or dashes, and start with a letter. Example: my-plugin/my-custom-block'
@@ -370,59 +426,23 @@ function translateBlockSettingUsingI18nSchema(
 
 /**
  * Registers a new block provided from metadata stored in `block.json` file.
- * It uses `registerBlockType` internally.
  *
- * @see registerBlockType
+ * @deprecated Use `registerBlockType` instead.
  *
  * @param {Object} metadata            Block metadata loaded from `block.json`.
- * @param {string} metadata.name       Block name.
- * @param {string} metadata.textdomain Textdomain to use with translations.
  * @param {Object} additionalSettings  Additional block settings.
  *
  * @return {?WPBlock} The block, if it has been successfully registered;
  *                    otherwise `undefined`.
  */
-export function registerBlockTypeFromMetadata(
-	{ name, textdomain, ...metadata },
-	additionalSettings
-) {
-	const allowedFields = [
-		'apiVersion',
-		'title',
-		'category',
-		'parent',
-		'icon',
-		'description',
-		'keywords',
-		'attributes',
-		'providesContext',
-		'usesContext',
-		'supports',
-		'styles',
-		'example',
-		'variations',
-	];
-
-	const settings = pick( metadata, allowedFields );
-
-	if ( textdomain ) {
-		Object.keys( i18nBlockSchema ).forEach( ( key ) => {
-			if ( ! settings[ key ] ) {
-				return;
-			}
-			settings[ key ] = translateBlockSettingUsingI18nSchema(
-				i18nBlockSchema[ key ],
-				settings[ key ],
-				textdomain
-			);
-		} );
-	}
-
-	unstable__bootstrapServerSideBlockDefinitions( {
-		[ name ]: settings,
+export function registerBlockTypeFromMetadata( metadata, additionalSettings ) {
+	deprecated( 'wp.blocks.registerBlockTypeFromMetadata', {
+		since: '10.7',
+		plugin: 'Gutenberg',
+		alternative: 'wp.blocks.registerBlockType',
+		version: '11.0',
 	} );
-
-	return registerBlockType( name, additionalSettings );
+	return registerBlockType( metadata, additionalSettings );
 }
 
 /**

packages/blocks/src/api/test/registration.js

@@ -17,7 +17,6 @@ import { blockDefault as blockIcon } from '@wordpress/icons';
  */
 import {
 	registerBlockType,
-	registerBlockTypeFromMetadata,
 	registerBlockCollection,
 	unregisterBlockCollection,
 	unregisterBlockType,
@@ -801,12 +800,10 @@ describe( 'blocks', () => {
 				expect( block1.attributes ).not.toEqual( block2.attributes );
 			} );
 		} );
-	} );
 
-	describe( 'registerBlockTypeFromMetadata', () => {
 		test( 'registers block from metadata', () => {
 			const Edit = () => 'test';
-			const block = registerBlockTypeFromMetadata(
+			const block = registerBlockType(
 				{
 					name: 'test/block-from-metadata',
 					title: 'Block from metadata',
@@ -859,7 +856,7 @@ describe( 'blocks', () => {
 			);
 
 			const Edit = () => 'test';
-			const block = registerBlockTypeFromMetadata(
+			const block = registerBlockType(
 				{
 					name: 'test/block-from-metadata-i18n',
 					title: 'I18n title from metadata',