Blocks: Add a way to manage block categories

blocks/api/categories.js

@@ -1,13 +1,22 @@
 /**
  * WordPress dependencies
  */
-import { select } from '@wordpress/data';
+import { dispatch, select } from '@wordpress/data';
 
 /**
  * Returns all the block categories.
  *
- * @return {Array} Block categories.
+ * @return {Object[]} Block categories.
  */
 export function getCategories() {
 	return select( 'core/blocks' ).getCategories();
 }
+
+/**
+ * Sets the block categories.
+ *
+ * @param {Object[]} categories Block categories.
+ */
+export function setCategories( categories ) {
+	dispatch( 'core/blocks' ).setCategories( categories );
+}

blocks/api/index.js

@@ -20,7 +20,10 @@ export {
 	getSaveElement,
 } from './serializer';
 export { isValidBlock } from './validation';
-export { getCategories } from './categories';
+export {
+	getCategories,
+	setCategories,
+} from './categories';
 export {
 	registerBlockType,
 	unregisterBlockType,

blocks/store/actions.js

@@ -58,3 +58,17 @@ export function setFallbackBlockName( name ) {
 		name,
 	};
 }
+
+/**
+ * Returns an action object used to set block categories.
+ *
+ * @param {Object[]} categories Block categories.
+ *
+ * @return {Object} Action object.
+ */
+export function setCategories( categories ) {
+	return {
+		type: 'SET_CATEGORIES',
+		categories,
+	};
+}

blocks/store/reducer.js

@@ -80,10 +80,8 @@ export const fallbackBlockName = createBlockNameSetterReducer( 'SET_FALLBACK_BLO
  * @return {Object} Updated state.
  */
 export function categories( state = DEFAULT_CATEGORIES, action ) {
-	if ( action.type === 'ADD_CATEGORIES' ) {
-		const addedSlugs = map( action.categories, ( category ) => category.slug );
-		const previousState = filter( state, ( category ) => addedSlugs.indexOf( category.slug ) === -1 );
-		return [ ...previousState, ...action.categories ];
+	if ( action.type === 'SET_CATEGORIES' ) {
+		return action.categories || [];
 	}
 
 	return state;

blocks/store/test/reducer.js

@@ -99,18 +99,17 @@ describe( 'categories', () => {
 		expect( categories( undefined, {} ) ).toEqual( DEFAULT_CATEGORIES );
 	} );
 
-	it( 'should add add a new category', () => {
+	it( 'should override categories', () => {
 		const original = deepFreeze( [
 			{ slug: 'chicken', title: 'Chicken' },
 		] );
 
 		const state = categories( original, {
-			type: 'ADD_CATEGORIES',
+			type: 'SET_CATEGORIES',
 			categories: [ { slug: 'wings', title: 'Wings' } ],
 		} );
 
 		expect( state ).toEqual( [
-			{ slug: 'chicken', title: 'Chicken' },
 			{ slug: 'wings', title: 'Wings' },
 		] );
 	} );

docs/extensibility/extending-blocks.md

@@ -189,9 +189,30 @@ On the server, you can filter the list of blocks shown in the inserter using the
 
 ```php
 add_filter( 'allowed_block_types', function( $allowed_block_types, $post ) {
-	if ( $post->post_type === 'post' ) {
+	if ( $post->post_type !== 'post' ) {
 	    return $allowed_block_types;
 	}
-	return [ 'core/paragraph' ];
+	return array( 'core/paragraph' );
+}, 10, 2 );
+```
+
+## Managing block categories
+
+It is possible to filter the list of default block categories using the `block_categories` filter. You can do it on the server by implementing a function which returns a list of categories. It is going to be used during blocks registration and to group blocks in the inserter. You can also use the second provided param `$post` to generate a different list depending on the post's content.
+
+```php
+add_filter( 'block_categories', function( $categories, $post ) {
+	if ( $post->post_type !== 'post' ) {
+		return $categories;
+	}
+	return array_merge(
+		$categories,
+		array(
+			array(
+				'slug' => 'my-category',
+				'title' => __( 'My category', 'my-plugin' ),
+			),
+		)
+	);
 }, 10, 2 );
 ```

lib/client-assets.php

@@ -982,6 +982,45 @@ function get_autosave_newer_than_post_save( $post ) {
 	return false;
 }
 
+/**
+ * Returns all the block categories.
+ *
+ * @since 2.2.0
+ *
+ * @param  WP_Post $post Post object.
+ * @return Object[] Block categories.
+ */
+function get_block_categories( $post ) {
+	$default_categories = array(
+		array(
+			'slug'  => 'common',
+			'title' => __( 'Common Blocks', 'gutenberg' ),
+		),
+		array(
+			'slug'  => 'formatting',
+			'title' => __( 'Formatting', 'gutenberg' ),
+		),
+		array(
+			'slug'  => 'layout',
+			'title' => __( 'Layout Elements', 'gutenberg' ),
+		),
+		array(
+			'slug'  => 'widgets',
+			'title' => __( 'Widgets', 'gutenberg' ),
+		),
+		array(
+			'slug'  => 'embed',
+			'title' => __( 'Embeds', 'gutenberg' ),
+		),
+		array(
+			'slug'  => 'shared',
+			'title' => __( 'Shared Blocks', 'gutenberg' ),
+		),
+	);
+
+	return apply_filters( 'block_categories', $default_categories, $post );
+}
+
 /**
  * Scripts & Styles.
  *
@@ -1043,6 +1082,12 @@ function gutenberg_editor_scripts_and_styles( $hook ) {
 		'after'
 	);
 
+	wp_add_inline_script(
+		'wp-blocks',
+		sprintf( 'wp.blocks.setCategories( %s );', wp_json_encode( get_block_categories( $post ) ) ),
+		'after'
+	);
+
 	// Prepopulate with some test content in demo.
 	if ( $is_new_post && $is_demo ) {
 		wp_add_inline_script(