Block Library: Make it possible to import individual blocks

packages/block-library/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### New Feature
+
+-   Made it possible to import individual blocks ([#42258](https://github.com/WordPress/gutenberg/pull/42258)). Check [README](./README.md#loading-individual-blocks) for more information.
+
 ## 7.13.0 (2022-08-24)
 
 ### Bug Fix

packages/block-library/README.md

@@ -12,62 +12,6 @@ npm install @wordpress/block-library --save
 
 _This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._
 
-## Building JavaScript for the browser
-
-If a `view.js` file (or a file prefixed with `view`, e.g. `view-example.js`) is present in the block's directory, this file will be built along other assets, making it available to load from the browser.
-
-This enables us to, for instance, load this file when the block is present on the page in two ways:
-
-1.  Using the block's `render_callback`:
-
-```php
-function render_block_my_block() {
-	$script_path = __DIR__ . '/my-block/view.js';
-
- 	if ( file_exists( $script_path ) ) {
- 		wp_enqueue_script(
- 			'wp-block-my-block-view',
- 			plugins_url( 'view.js', $script_path ),
- 			array(),
- 			false,
- 			true
- 		);
- 	}
-}
-
-function register_block_my_block() {
-	register_block_type(
-		__DIR__ . '/my-block',
-		array(
-			'render_callback' => 'render_block_my_block',
-		)
-	);
-}
-
-
-add_action( 'init', 'register_block_my_block' );
-```
-
-2.  Using the `render_block` filter:
-
-```php
-function render_block_my_block() {
-	$script_path = __DIR__ . '/my-block/view.js';
-
- 	if ( file_exists( $script_path ) ) {
- 		wp_enqueue_script(
- 			'wp-block-my-block-view',
- 			plugins_url( 'view.js', $script_path ),
- 			array(),
- 			false,
- 			true
- 		);
- 	}
-}
-
-apply_filter( 'render_block', 'render_block_my_block' );
-```
-
 ## API
 
 <!-- START TOKEN(Autogenerated API docs) -->
@@ -90,6 +34,28 @@ _Parameters_
 
 <!-- END TOKEN(Autogenerated API docs) -->
 
+## Registering individual blocks
+
+1.  When you only care about registering the block when file gets imported:
+
+    ```js
+    import '@wordpress/block-library/build-module/verse/init';
+    ```
+
+2.  When you want to use the reference to the block after it gets automatically registered:
+
+    ```js
+    import verseBlock from '@wordpress/block-library/build-module/verse/init';
+    ```
+
+3.  When you need a full control over when the block gets registered:
+
+    ```js
+    import { init } from '@wordpress/block-library/build-module/verse';
+
+    const verseBlock = init();
+    ```
+
 ## Contributing to this package
 
 This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.
@@ -100,17 +66,57 @@ To find out more about contributing to this package or Gutenberg as a whole, ple
 
 ⚠️ Adding new blocks to this package **requires** additional steps!
 
-1.  Do not forget to register your new block in the [`index.js`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/index.js) file of this package. For example, if you were to add a new core block called `core/blinking-paragraph`, you would have to add something like:
+1.  Do not forget to register a new core block in the [`index.js`](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/index.js) file of this package. For example, if you were to add the new core block called `core/blinking-paragraph`, you would have to add something like:
 
     ```js
     // packages/block-library/src/index.js
     import * as blinkingParagraph from './blinking-paragraph';
+    ```
+
+    Then add `blinkingParagraph` to the list in the `getAllBlocks()` function.
+
+    If it's experimental, add the following property to `block. json`:
+
+    ```json
+    {
+    	"__experimental": "true"
+    }
+    ```
 
-    // Then add `blinkingParagraph` to `getAllBlocks()`
-    // If it's experimental, add the following property to block.json:
-    __experimental: 'true';
+2.  Register the 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).
+
+3.  Add `init.js` file to the directory of the new block:
+
+    ```js
+    /**
+     * Internal dependencies
+     */
+    import { init } from './';
+
+    export default init();
     ```
 
-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).
+    This file is used when using the option to register individual block from the `@wordpress/block-library` package.
+
+4.  If a `view.js` file (or a file prefixed with `view`, e.g. `view-example.js`) is present in the block's directory, this file will be built along other assets, making it available to load from the browser. You only need to reference a `view.min.js` (notice the different file extension) file in the `block.json` file as follows:
+
+    ```json
+    {
+    	"viewScript": "file:./view.min.js"
+    }
+    ```
+
+    This file will get automatically loaded when the static block is present on the front end. For dynamic block, you need to manually enqueue the view script in `render_callback` of the block, example:
+
+    ```php
+    function render_block_core_blinking_paragraph( $attributes, $content ) {
+        $should_load_view_script = ! empty( $attributes['isInteractive'] ) && ! wp_script_is( 'wp-block-blinking-paragraph-view' );
+        if ( $should_load_view_script ) {
+    	    wp_enqueue_script( 'wp-block-blinking-paragraph-view' );
+        }
+
+    	return $content;
+    }
+    ```
 
 <br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>

packages/block-library/babel-plugin.js

@@ -6,7 +6,7 @@ const fs = require( 'fs' );
 /**
  * Internal dependencies
  */
-const isBlockMetadataExperimental = require( './src/is-block-metadata-experimental' );
+const isBlockMetadataExperimental = require( './src/utils/is-block-metadata-experimental' );
 
 /**
  * Creates a babel plugin that replaces experimental block imports with

packages/block-library/package.json

@@ -27,10 +27,7 @@
 	"sideEffects": [
 		"build-style/**",
 		"src/**/*.scss",
-		"src/navigation-link/index.js",
-		"src/template-part/index.js",
-		"src/query/index.js",
-		"src/post-terms/index.js"
+		"{src,build,build-module}/*/init.js"
 	],
 	"dependencies": {
 		"@babel/runtime": "^7.16.0",

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

@@ -6,6 +6,7 @@ import { archive as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import metadata from './block.json';
 import edit from './edit';
 
@@ -18,3 +19,5 @@ export const settings = {
 	example: {},
 	edit,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/archives/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

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

@@ -6,6 +6,7 @@ import { audio as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import deprecated from './deprecated';
 import edit from './edit';
 import metadata from './block.json';
@@ -28,3 +29,5 @@ export const settings = {
 	edit,
 	save,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/audio/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

packages/block-library/src/audio/transforms.native.js

@@ -2,7 +2,7 @@
  * Internal dependencies
  */
 import webTransforms from './transforms.js';
-import transformationCategories from '../transformationCategories';
+import transformationCategories from '../utils/transformation-categories';
 
 const transforms = {
 	...webTransforms,

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

@@ -6,6 +6,7 @@ import { commentAuthorAvatar as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import metadata from './block.json';
 import edit from './edit';
 
@@ -16,3 +17,5 @@ export const settings = {
 	icon,
 	edit,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/avatar/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

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

@@ -6,6 +6,7 @@ import { symbol as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import metadata from './block.json';
 import edit from './edit';
 
@@ -17,3 +18,5 @@ export const settings = {
 	edit,
 	icon,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/block/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

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

@@ -7,6 +7,7 @@ import { button as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import deprecated from './deprecated';
 import edit from './edit';
 import metadata from './block.json';
@@ -32,3 +33,5 @@ export const settings = {
 		text: ( a.text || '' ) + text,
 	} ),
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/button/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

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

@@ -7,6 +7,7 @@ import { buttons as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import deprecated from './deprecated';
 import transforms from './transforms';
 import edit from './edit';
@@ -36,3 +37,5 @@ export const settings = {
 	edit,
 	save,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/buttons/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

packages/block-library/src/buttons/transforms.native.js

@@ -2,7 +2,7 @@
  * Internal dependencies
  */
 import webTransforms from './transforms.js';
-import transformationCategories from '../transformationCategories';
+import transformationCategories from '../utils/transformation-categories';
 
 const transforms = {
 	...webTransforms,

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

@@ -6,6 +6,7 @@ import { calendar as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import metadata from './block.json';
 import edit from './edit';
 import transforms from './transforms';
@@ -20,3 +21,5 @@ export const settings = {
 	edit,
 	transforms,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/calendar/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

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

@@ -6,6 +6,7 @@ import { category as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import metadata from './block.json';
 import edit from './edit';
 
@@ -18,3 +19,5 @@ export const settings = {
 	example: {},
 	edit,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/categories/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();

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

@@ -7,6 +7,7 @@ import { code as icon } from '@wordpress/icons';
 /**
  * Internal dependencies
  */
+import initBlock from '../utils/init-block';
 import edit from './edit';
 import metadata from './block.json';
 import save from './save';
@@ -32,3 +33,5 @@ export const settings = {
 	edit,
 	save,
 };
+
+export const init = () => initBlock( { name, metadata, settings } );

packages/block-library/src/code/init.js

@@ -0,0 +1,6 @@
+/**
+ * Internal dependencies
+ */
+import { init } from './';
+
+export default init();