Enables Block Grouping/UnGrouping using core/group

docs/designers-developers/developers/block-api/block-registration.md

@@ -311,6 +311,40 @@ transforms: {
 ```
 {% end %}
 
+In addition to accepting an array of known block types, the `blocks` option also accepts a "wildcard" (`"*"`). This allows for transformations which apply to _all_ block types (eg: all blocks can transform into `core/group`):
+
+{% codetabs %}
+{% ES5 %}
+```js
+transforms: {
+    from: [
+        {
+            type: 'block',
+            blocks: [ '*' ], // wildcard - match any block
+            transform: function( attributes, innerBlocks ) {
+                // transform logic here
+            },
+        },
+    ],
+},
+```
+{% ESNext %}
+```js
+transforms: {
+    from: [
+        {
+            type: 'block',
+            blocks: [ '*' ], // wildcard - match any block
+            transform: ( attributes, innerBlocks ) => {
+                // transform logic here
+            },
+        },
+    ],
+},
+```
+{% end %}
+
+
 A block with innerBlocks can also be transformed from and to another block with innerBlocks.
 
 {% codetabs %}

packages/block-editor/src/components/block-actions/index.js

@@ -8,13 +8,15 @@ import { castArray, first, last, every } from 'lodash';
  */
 import { compose } from '@wordpress/compose';
 import { withSelect, withDispatch } from '@wordpress/data';
-import { cloneBlock, hasBlockSupport } from '@wordpress/blocks';
+import { cloneBlock, hasBlockSupport, switchToBlockType } from '@wordpress/blocks';
 
 function BlockActions( {
 	onDuplicate,
 	onRemove,
 	onInsertBefore,
 	onInsertAfter,
+	onGroup,
+	onUngroup,
 	isLocked,
 	canDuplicate,
 	children,
@@ -24,6 +26,8 @@ function BlockActions( {
 		onRemove,
 		onInsertAfter,
 		onInsertBefore,
+		onGroup,
+		onUngroup,
 		isLocked,
 		canDuplicate,
 	} );
@@ -65,6 +69,7 @@ export default compose( [
 			multiSelect,
 			removeBlocks,
 			insertDefaultBlock,
+			replaceBlocks,
 		} = dispatch( 'core/block-editor' );
 
 		return {
@@ -107,6 +112,39 @@ export default compose( [
 					insertDefaultBlock( {}, rootClientId, lastSelectedIndex + 1 );
 				}
 			},
+			onGroup() {
+				if ( ! blocks.length ) {
+					return;
+				}
+
+				// Activate the `transform` on `core/group` which does the conversion
+				const newBlocks = switchToBlockType( blocks, 'core/group' );
+
+				if ( ! newBlocks ) {
+					return;
+				}
+				replaceBlocks(
+					clientIds,
+					newBlocks
+				);
+			},
+
+			onUngroup() {
+				if ( ! blocks.length ) {
+					return;
+				}
+
+				const innerBlocks = blocks[ 0 ].innerBlocks;
+
+				if ( ! innerBlocks.length ) {
+					return;
+				}
+
+				replaceBlocks(
+					clientIds,
+					innerBlocks
+				);
+			},
 		};
 	} ),
 ] )( BlockActions );

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

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
+import { createBlock } from '@wordpress/blocks';
 
 /**
  * Internal dependencies
@@ -25,6 +26,45 @@ export const settings = {
 		anchor: true,
 		html: false,
 	},
+
+	transforms: {
+		from: [
+			{
+				type: 'block',
+				isMultiBlock: true,
+				blocks: [ '*' ],
+				convert( blocks ) {
+					// Avoid transforming a single `core/group` Block
+					if ( blocks.length === 1 && blocks[ 0 ].name === 'core/group' ) {
+						return;
+					}
+
+					const alignments = [ 'wide', 'full' ];
+
+					// Determine the widest setting of all the blocks to be grouped
+					const widestAlignment = blocks.reduce( ( result, block ) => {
+						const { align } = block.attributes;
+						return alignments.indexOf( align ) > alignments.indexOf( result ) ? align : result;
+					}, undefined );
+
+					// Clone the Blocks to be Grouped
+					// Failing to create new block references causes the original blocks
+					// to be replaced in the switchToBlockType call thereby meaning they
+					// are removed both from their original location and within the
+					// new group block.
+					const groupInnerBlocks = blocks.map( ( block ) => {
+						return createBlock( block.name, block.attributes, block.innerBlocks );
+					} );
+
+					return createBlock( 'core/group', {
+						align: widestAlignment,
+					}, groupInnerBlocks );
+				},
+			},
+
+		],
+	},
+
 	edit,
 	save,
 };

packages/blocks/CHANGELOG.md

@@ -3,6 +3,8 @@
 ### New Feature
 
 - Added a default implementation for `save` setting in `registerBlockType` which saves no markup in the post content.
+- Added wildcard block transforms which allows for transforming all/any blocks in another block.
+- Added `convert()` method option to `transforms` definition. It receives complete block object(s) as it's argument(s). It is now preferred over the older `transform()` (note that `transform()` is still fully supported).
 
 ## 6.1.0 (2019-03-06)
 

packages/blocks/README.md

@@ -679,7 +679,7 @@ _Parameters_
 
 _Returns_
 
--   `Array`: Array of blocks.
+-   `?Array`: Array of blocks or null.
 
 <a name="synchronizeBlocksWithTemplate" href="#synchronizeBlocksWithTemplate">#</a> **synchronizeBlocksWithTemplate**
 

packages/blocks/src/api/factory.js

@@ -11,6 +11,7 @@ import {
 	filter,
 	first,
 	flatMap,
+	has,
 	uniq,
 	isFunction,
 	isEmpty,
@@ -117,26 +118,41 @@ const isPossibleTransformForSource = ( transform, direction, blocks ) => {
 		return false;
 	}
 
-	// If multiple blocks are selected, only multi block transforms are allowed.
+	// If multiple blocks are selected, only multi block transforms
+	// or wildcard transforms are allowed.
 	const isMultiBlock = blocks.length > 1;
-	const isValidForMultiBlocks = ! isMultiBlock || transform.isMultiBlock;
+	const firstBlockName = first( blocks ).name;
+	const isValidForMultiBlocks = isWildcardBlockTransform( transform ) || ! isMultiBlock || transform.isMultiBlock;
 	if ( ! isValidForMultiBlocks ) {
 		return false;
 	}
 
+	// Check non-wildcard transforms to ensure that transform is valid
+	// for a block selection of multiple blocks of different types
+	if ( ! isWildcardBlockTransform( transform ) && ! every( blocks, { name: firstBlockName } ) ) {
+		return false;
+	}
+
 	// Only consider 'block' type transforms as valid.
 	const isBlockType = transform.type === 'block';
 	if ( ! isBlockType ) {
 		return false;
 	}
 
-	// Check if the transform's block name matches the source block only if this is a transform 'from'.
+	// Check if the transform's block name matches the source block (or is a wildcard)
+	// only if this is a transform 'from'.
 	const sourceBlock = first( blocks );
-	const hasMatchingName = direction !== 'from' || transform.blocks.indexOf( sourceBlock.name ) !== -1;
+	const hasMatchingName = direction !== 'from' || transform.blocks.indexOf( sourceBlock.name ) !== -1 || isWildcardBlockTransform( transform );
 	if ( ! hasMatchingName ) {
 		return false;
 	}
 
+	// Don't allow single 'core/group' blocks to be transformed into
+	// a 'core/group' block.
+	if ( ! isMultiBlock && isContainerGroupBlock( sourceBlock.name ) && isContainerGroupBlock( transform.blockName ) ) {
+		return false;
+	}
+
 	// If the transform has a `isMatch` function specified, check that it returns true.
 	if ( isFunction( transform.isMatch ) ) {
 		const attributes = transform.isMultiBlock ? blocks.map( ( block ) => block.attributes ) : sourceBlock.attributes;
@@ -171,7 +187,9 @@ const getBlockTypesForPossibleFromTransforms = ( blocks ) => {
 
 			return !! findTransform(
 				fromTransforms,
-				( transform ) => isPossibleTransformForSource( transform, 'from', blocks )
+				( transform ) => {
+					return isPossibleTransformForSource( transform, 'from', blocks );
+				}
 			);
 		},
 	);
@@ -199,7 +217,9 @@ const getBlockTypesForPossibleToTransforms = ( blocks ) => {
 	// filter all 'to' transforms to find those that are possible.
 	const possibleTransforms = filter(
 		transformsTo,
-		( transform ) => isPossibleTransformForSource( transform, 'to', blocks )
+		( transform ) => {
+			return transform && isPossibleTransformForSource( transform, 'to', blocks );
+		}
 	);
 
 	// Build a list of block names using the possible 'to' transforms.
@@ -212,6 +232,45 @@ const getBlockTypesForPossibleToTransforms = ( blocks ) => {
 	return blockNames.map( ( name ) => getBlockType( name ) );
 };
 
+/**
+ * Determines whether transform is a "block" type
+ * and if so whether it is a "wildcard" transform
+ * ie: targets "any" block type
+ *
+ * @param {Object} t the Block transform object
+ *
+ * @return {boolean} whether transform is a wildcard transform
+ */
+export const isWildcardBlockTransform = ( t ) => t && t.type === 'block' && Array.isArray( t.blocks ) && t.blocks.includes( '*' );
+
+/**
+ * Determines whether the given Block is the core Block which
+ * acts as a container Block for other Blocks as part of the
+ * Grouping mechanics
+ *
+ * @param  {string} name the name of the Block to test against
+ *
+ * @return {boolean} whether or not the Block is the container Block type
+ */
+export const isContainerGroupBlock = ( name ) => name === 'core/group';
+
+/**
+ * Determines whether the provided Blocks are of the same type
+ * (eg: all `core/paragraph`).
+ *
+ * @param  {Array}  blocksArray the Block definitions
+ *
+ * @return {boolean} whether or not the given Blocks pass the criteria
+ */
+export const isBlockSelectionOfSameType = ( blocksArray = [] ) => {
+	if ( ! blocksArray.length ) {
+		return false;
+	}
+	const sourceName = blocksArray[ 0 ].name;
+
+	return every( blocksArray, [ 'name', sourceName ] );
+};
+
 /**
  * Returns an array of block types that the set of blocks received as argument
  * can be transformed into.
@@ -225,12 +284,6 @@ export function getPossibleBlockTransformations( blocks ) {
 		return [];
 	}
 
-	const sourceBlock = first( blocks );
-	const isMultiBlock = blocks.length > 1;
-	if ( isMultiBlock && ! every( blocks, { name: sourceBlock.name } ) ) {
-		return [];
-	}
-
 	const blockTypesForFromTransforms = getBlockTypesForPossibleFromTransforms( blocks );
 	const blockTypesForToTransforms = getBlockTypesForPossibleToTransforms( blocks );
 
@@ -313,30 +366,34 @@ export function getBlockTransforms( direction, blockTypeOrName ) {
  * @param {Array|Object} blocks Blocks array or block object.
  * @param {string}       name   Block name.
  *
- * @return {Array} Array of blocks.
+ * @return {?Array} Array of blocks or null.
  */
 export function switchToBlockType( blocks, name ) {
 	const blocksArray = castArray( blocks );
 	const isMultiBlock = blocksArray.length > 1;
 	const firstBlock = blocksArray[ 0 ];
 	const sourceName = firstBlock.name;
 
-	if ( isMultiBlock && ! every( blocksArray, ( block ) => ( block.name === sourceName ) ) ) {
+	// Unless it's a `core/group` Block then for multi block selections
+	// check that all Blocks are of the same type otherwise
+	// we can't run a conversion
+	if ( ! isContainerGroupBlock( name ) && isMultiBlock && ! isBlockSelectionOfSameType( blocksArray ) ) {
 		return null;
 	}
 
 	// Find the right transformation by giving priority to the "to"
 	// transformation.
 	const transformationsFrom = getBlockTransforms( 'from', name );
 	const transformationsTo = getBlockTransforms( 'to', sourceName );
+
 	const transformation =
 		findTransform(
 			transformationsTo,
-			( t ) => t.type === 'block' && t.blocks.indexOf( name ) !== -1 && ( ! isMultiBlock || t.isMultiBlock )
+			( t ) => t.type === 'block' && ( ( isWildcardBlockTransform( t ) ) || t.blocks.indexOf( name ) !== -1 ) && ( ! isMultiBlock || t.isMultiBlock )
 		) ||
 		findTransform(
 			transformationsFrom,
-			( t ) => t.type === 'block' && t.blocks.indexOf( sourceName ) !== -1 && ( ! isMultiBlock || t.isMultiBlock )
+			( t ) => t.type === 'block' && ( ( isWildcardBlockTransform( t ) ) || t.blocks.indexOf( sourceName ) !== -1 ) && ( ! isMultiBlock || t.isMultiBlock )
 		);
 
 	// Stop if there is no valid transformation.
@@ -345,11 +402,18 @@ export function switchToBlockType( blocks, name ) {
 	}
 
 	let transformationResults;
+
 	if ( transformation.isMultiBlock ) {
-		transformationResults = transformation.transform(
-			blocksArray.map( ( currentBlock ) => currentBlock.attributes ),
-			blocksArray.map( ( currentBlock ) => currentBlock.innerBlocks )
-		);
+		if ( has( transformation, 'convert' ) ) {
+			transformationResults = transformation.convert( blocksArray );
+		} else {
+			transformationResults = transformation.transform(
+				blocksArray.map( ( currentBlock ) => currentBlock.attributes ),
+				blocksArray.map( ( currentBlock ) => currentBlock.innerBlocks ),
+			);
+		}
+	} else if ( has( transformation, 'convert' ) ) {
+		transformationResults = transformation.convert( firstBlock );
 	} else {
 		transformationResults = transformation.transform( firstBlock.attributes, firstBlock.innerBlocks );
 	}