Declare blocks as __experimental in block.json to automate syncing Gu…

…tenberg packages to WordPress (#40655)

* Declare blocks as __experimental in block.json to automate syncing Gutenberg packages to WordPress

* Only apply the plugin to block-library/src/index.js via babel.config.js

* Remove navigation area documentation that got added by accident

* Switch to replacing imports with null variable declarations

* Fix broken test and remove nav area documentation

* Update packages/block-library/src/index.js

Co-authored-by: Greg Ziółkowski <[email protected]>

* Add a changelog entry

Co-authored-by: Greg Ziółkowski <[email protected]>

babel.config.js

@@ -4,5 +4,13 @@ module.exports = ( api ) => {
 	return {
 		presets: [ '@wordpress/babel-preset-default' ],
 		plugins: [ '@emotion/babel-plugin', 'babel-plugin-inline-json-import' ],
+		overrides: [
+			{
+				test: 'packages/block-library/src/index.js',
+				plugins: [
+					require.resolve( '@wordpress/block-library/babel-plugin' ),
+				],
+			},
+		],
 	};
 };

packages/block-library/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancement
+
+-   Declare blocks as __experimental in block.json to automate syncing Gutenberg packages to WordPress ([#40655](https://github.com/WordPress/gutenberg/pull/40655)).
+
 ## 7.5.0 (2022-05-04)
 
 ## 7.4.0 (2022-04-21)

packages/block-library/README.md

@@ -106,8 +106,9 @@ To find out more about contributing to this package or Gutenberg as a whole, ple
     // packages/block-library/src/index.js
     import * as blinkingParagraph from './blinking-paragraph';
 
-    // Then add `blinkingParagraph` to either `__experimentalGetCoreBlocks()`
-    // or `__experimentalRegisterExperimentalCoreBlocks()`
+    // Then add `blinkingParagraph` to `getAllBlocks()`
+    // If it's experimental, add the following property to block.json:
+    __experimental: 'true';
     ```
 
 2.  Register your block in the `gutenberg_reregister_core_block_types()` function of the [`lib/blocks.php`](https://github.com/WordPress/gutenberg/blob/trunk/lib/blocks.php) file. Add it to the `block_folders` array if it's a [static block](https://developer.wordpress.org/block-editor/explanations/glossary/#static-block) or to the `block_names` array if it's a [dynamic block](https://developer.wordpress.org/block-editor/explanations/glossary/#dynamic-block).

packages/block-library/babel-plugin.js

@@ -0,0 +1,154 @@
+/**
+ * External dependencies
+ */
+const fs = require( 'fs' );
+
+/**
+ * Internal dependencies
+ */
+const isBlockMetadataExperimental = require( './src/is-block-metadata-experimental' );
+
+/**
+ * Creates a babel plugin that replaces experimental block imports with
+ * null variable declarations.
+ *
+ * For example:
+ *     import * as experimentalBlock from "./experimental-block";
+ * On build becomes:
+ *     const experimentalBlock = null;
+ *
+ * This ensures the dead code elimination removes the experimental blocks modules
+ * during the production build.
+ *
+ * For more context, see https://github.com/WordPress/gutenberg/pull/40655/
+ *
+ * @param {Function} shouldProcessImport Optional callback to decide whether a given import should be processed.
+ * @param {boolean}  isGutenbergPlugin   Whether to run the plugin.
+ */
+function createBabelPlugin( shouldProcessImport, isGutenbergPlugin ) {
+	if ( ! shouldProcessImport ) {
+		shouldProcessImport = isImportDeclarationAnExperimentalBlock;
+	}
+	if ( isGutenbergPlugin === undefined ) {
+		// process.env.npm_package_config_IS_GUTENBERG_PLUGIN is a string, not a boolean
+		isGutenbergPlugin =
+			String( process.env.npm_package_config_IS_GUTENBERG_PLUGIN ) ===
+			'true';
+	}
+	/**
+	 * The babel plugin created by createBabelPlugin.
+	 *
+	 * @see createBabelPlugin.
+	 * @param {import('@babel/core')} babel Current Babel object.
+	 * @return {import('@babel/core').PluginObj} Babel plugin object.
+	 */
+	return function babelPlugin( { types: t } ) {
+		if ( isGutenbergPlugin ) {
+			return {};
+		}
+
+		return {
+			visitor: {
+				ImportDeclaration( path ) {
+					// Only process the experimental blocks.
+					if ( ! shouldProcessImport( path ) ) {
+						return;
+					}
+
+					// Get the imported variable name.
+					const namespaceSpecifier = path.node.specifiers.find(
+						( specifier ) =>
+							specifier.type === 'ImportNamespaceSpecifier'
+					);
+					const { name } = namespaceSpecifier.local;
+
+					path.replaceWith(
+						t.variableDeclaration( 'const', [
+							t.variableDeclarator(
+								t.identifier( name ),
+								t.nullLiteral()
+							),
+						] )
+					);
+				},
+			},
+		};
+	};
+}
+
+/**
+ * Tests whether an import declaration refers to an experimental block.
+ * In broad strokes, it's a block that says "__experimental" in its block.json file.
+ * For details, check the implementation.
+ *
+ * @param {Object} path Babel.js AST path representing the import declaration,
+ * @return {boolean} Whether the import represents an experimental block.
+ */
+function isImportDeclarationAnExperimentalBlock( path ) {
+	// Only look for wildcard imports like import * as a from "source":
+	const { node } = path;
+	const namespaceSpecifier = node.specifiers.find(
+		( specifier ) => specifier.type === 'ImportNamespaceSpecifier'
+	);
+	if ( ! namespaceSpecifier || ! namespaceSpecifier.local ) {
+		return;
+	}
+
+	// Only look for imports starting with ./ and without additional slashes in the path.
+	const importedPath = node.source.value;
+	if (
+		! importedPath ||
+		! importedPath.startsWith( './' ) ||
+		importedPath.split( '/' ).length > 2
+	) {
+		return false;
+	}
+
+	// Check the imported directory has a related block.json file.
+	const blockJsonPath = __dirname + '/src/' + importedPath + '/block.json';
+	if ( ! fs.existsSync( blockJsonPath ) ) {
+		return false;
+	}
+
+	// Read the block.json file related to this block
+	const { name } = namespaceSpecifier.local;
+	let blockJSONBuffer;
+	try {
+		blockJSONBuffer = fs.readFileSync( blockJsonPath );
+	} catch ( e ) {
+		process.stderr.write(
+			'Could not read block.json for the module "' +
+				importedPath +
+				'" imported under name "' +
+				name +
+				'" from path "' +
+				blockJsonPath +
+				'"'
+		);
+		throw e;
+	}
+	let blockJSON;
+	try {
+		blockJSON = JSON.parse( blockJSONBuffer );
+	} catch ( e ) {
+		process.stderr.write(
+			'Could not parse block.json for the module "' +
+				importedPath +
+				'" imported under name "' +
+				name +
+				'" read from path "' +
+				blockJsonPath +
+				'"'
+		);
+		throw e;
+	}
+	if ( ! isBlockMetadataExperimental( blockJSON ) ) {
+		return false;
+	}
+
+	return true;
+}
+
+const babelPlugin = createBabelPlugin();
+babelPlugin.createBabelPlugin = createBabelPlugin;
+module.exports = babelPlugin;

packages/block-library/src/comment-author-avatar/block.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
+	"__experimental": "fse",
 	"name": "core/comment-author-avatar",
 	"title": "Comment Author Avatar (deprecated)",
 	"category": "theme",

packages/block-library/src/index.js

@@ -12,6 +12,15 @@ import {
 /**
  * Internal dependencies
  */
+// When IS_GUTENBERG_PLUGIN is set to false, imports of experimental blocks
+// are transformed by packages/block-library/src/index.js as follows:
+//    import * as experimentalBlock from './experimental-block'
+// becomes
+//    const experimentalBlock = null;
+// This enables webpack to eliminate the experimental blocks code from the
+// production build to make the final bundle smaller.
+//
+// See https://github.com/WordPress/gutenberg/pull/40655 for more context.
 import * as archives from './archives';
 import * as avatar from './avatar';
 import * as audio from './audio';
@@ -107,6 +116,8 @@ import * as textColumns from './text-columns';
 import * as verse from './verse';
 import * as video from './video';
 
+import isBlockMetadataExperimental from './is-block-metadata-experimental';
+
 /**
  * Function to register an individual block.
  *
@@ -122,23 +133,17 @@ const registerBlock = ( block ) => {
 };
 
 /**
- * Function to get all the core blocks in an array.
- *
- * @example
- * ```js
- * import { __experimentalGetCoreBlocks } from '@wordpress/block-library';
- *
- * const coreBlocks = __experimentalGetCoreBlocks();
- * ```
+ * Function to get all the block-library blocks in an array
  */
-export const __experimentalGetCoreBlocks = () => [
+const getAllBlocks = () => [
 	// Common blocks are grouped at the top to prioritize their display
 	// in various contexts — like the inserter and auto-complete components.
 	paragraph,
 	image,
 	heading,
 	gallery,
 	list,
+	listItem,
 	quote,
 
 	// Register all remaining core blocks.
@@ -152,6 +157,7 @@ export const __experimentalGetCoreBlocks = () => [
 	code,
 	column,
 	columns,
+	commentAuthorAvatar,
 	cover,
 	embed,
 	file,
@@ -196,6 +202,10 @@ export const __experimentalGetCoreBlocks = () => [
 	postFeaturedImage,
 	postContent,
 	postAuthor,
+	postAuthorName,
+	postComment,
+	postCommentsCount,
+	postCommentsLink,
 	postDate,
 	postTerms,
 	postNavigationLink,
@@ -220,13 +230,29 @@ export const __experimentalGetCoreBlocks = () => [
 	commentsPaginationPrevious,
 	postComments,
 	postCommentsForm,
+	tableOfContents,
 	homeLink,
 	logInOut,
 	termDescription,
 	queryTitle,
 	postAuthorBiography,
 ];
 
+/**
+ * Function to get all the core blocks in an array.
+ *
+ * @example
+ * ```js
+ * import { __experimentalGetCoreBlocks } from '@wordpress/block-library';
+ *
+ * const coreBlocks = __experimentalGetCoreBlocks();
+ * ```
+ */
+export const __experimentalGetCoreBlocks = () =>
+	getAllBlocks().filter(
+		( { metadata } ) => ! isBlockMetadataExperimental( metadata )
+	);
+
 /**
  * Function to register core blocks provided by the block editor.
  *
@@ -266,23 +292,19 @@ export const registerCoreBlocks = (
 export const __experimentalRegisterExperimentalCoreBlocks = process.env
 	.IS_GUTENBERG_PLUGIN
 	? ( { enableFSEBlocks } = {} ) => {
-			[
-				// Experimental blocks.
-				postAuthorName,
-				tableOfContents,
-				...( window.__experimentalEnableListBlockV2
-					? [ listItem ]
-					: [] ),
-
-				// Full Site Editing blocks.
-				...( enableFSEBlocks
-					? [
-							commentAuthorAvatar,
-							postComment,
-							postCommentsCount,
-							postCommentsLink,
-					  ]
-					: [] ),
-			].forEach( registerBlock );
+			const enabledExperiments = [
+				window.__experimentalEnableListBlockV2 ? 'list-v2' : null,
+				enableFSEBlocks ? 'fse' : null,
+			];
+			getAllBlocks()
+				.filter( ( { metadata } ) =>
+					isBlockMetadataExperimental( metadata )
+				)
+				.filter(
+					( { metadata: { __experimental } } ) =>
+						__experimental === true ||
+						enabledExperiments.includes( __experimental )
+				)
+				.forEach( registerBlock );
 	  }
 	: undefined;

packages/block-library/src/is-block-metadata-experimental.js

@@ -0,0 +1,19 @@
+/**
+ * Checks if the block is experimental based on the metadata loaded
+ * from block.json.
+ *
+ * This function is in a separate file and uses the older JS syntax so
+ * that it can be imported in both:
+ * – block-library/src/index.js
+ * – block-library/src/babel-plugin.js
+ *
+ * @param {Object} metadata Parsed block.json metadata.
+ * @return {boolean} Is the block experimental?
+ */
+module.exports = function isBlockMetadataExperimental( metadata ) {
+	return (
+		metadata &&
+		'__experimental' in metadata &&
+		metadata.__experimental !== false
+	);
+};

packages/block-library/src/list-item/block.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
+	"__experimental": "list-v2",
 	"name": "core/list-item",
 	"title": "List item",
 	"category": "text",

packages/block-library/src/post-author-name/block.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
+	"__experimental": true,
 	"name": "core/post-author-name",
 	"title": "Post Author Name",
 	"category": "theme",

packages/block-library/src/post-comment/block.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
+	"__experimental": "fse",
 	"name": "core/post-comment",
 	"title": "Post Comment (deprecated)",
 	"category": "theme",

packages/block-library/src/post-comments-count/block.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
+	"__experimental": "fse",
 	"name": "core/post-comments-count",
 	"title": "Post Comments Count",
 	"category": "theme",

packages/block-library/src/post-comments-link/block.json

@@ -1,6 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/block.json",
 	"apiVersion": 2,
+	"__experimental": "fse",
 	"name": "core/post-comments-link",
 	"title": "Post Comments Link",
 	"category": "theme",