Blocks: Promote block variations to stable API

docs/designers-developers/developers/data/data-core-blocks.md

@@ -59,6 +59,20 @@ _Returns_
 
 -   `Array`: Block Types.
 
+<a name="getBlockVariations" href="#getBlockVariations">#</a> **getBlockVariations**
+
+Returns block variations by block name.
+
+_Parameters_
+
+-   _state_ `Object`: Data state.
+-   _blockName_ `string`: Block type name.
+-   _scope_ `[WPBlockVariationScope]`: Block variation scope name.
+
+_Returns_
+
+-   `(Array<WPBlockVariation>|void)`: Block variations.
+
 <a name="getCategories" href="#getCategories">#</a> **getCategories**
 
 Returns all the available categories.
@@ -108,6 +122,23 @@ _Returns_
 
 -   `?string`: Default block name.
 
+<a name="getDefaultBlockVariation" href="#getDefaultBlockVariation">#</a> **getDefaultBlockVariation**
+
+Returns the default block variation for the given block type.
+When there are multiple variations annotated as the default one,
+the last added item is picked. This simplifies registering overrides.
+When there is no default variation set, it returns the first item.
+
+_Parameters_
+
+-   _state_ `Object`: Data state.
+-   _blockName_ `string`: Block type name.
+-   _scope_ `[WPBlockVariationScope]`: Block variation scope name.
+
+_Returns_
+
+-   `?WPBlockVariation`: The default block variation.
+
 <a name="getFreeformFallbackBlockName" href="#getFreeformFallbackBlockName">#</a> **getFreeformFallbackBlockName**
 
 Returns the name of the block for handling non-block content.
@@ -246,6 +277,19 @@ _Returns_
 
 -   `Object`: Action object.
 
+<a name="addBlockVariations" href="#addBlockVariations">#</a> **addBlockVariations**
+
+Returns an action object used in signalling that new block variations have been added.
+
+_Parameters_
+
+-   _blockName_ `string`: Block name.
+-   _variations_ `(WPBlockVariation|Array<WPBlockVariation>)`: Block variations.
+
+_Returns_
+
+-   `Object`: Action object.
+
 <a name="removeBlockCollection" href="#removeBlockCollection">#</a> **removeBlockCollection**
 
 Returns an action object used to remove block collections
@@ -283,6 +327,19 @@ _Returns_
 
 -   `Object`: Action object.
 
+<a name="removeBlockVariations" href="#removeBlockVariations">#</a> **removeBlockVariations**
+
+Returns an action object used in signalling that block variations have been removed.
+
+_Parameters_
+
+-   _blockName_ `string`: Block name.
+-   _variationNames_ `(string|Array<string>)`: Block variation names.
+
+_Returns_
+
+-   `Object`: Action object.
+
 <a name="setCategories" href="#setCategories">#</a> **setCategories**
 
 Returns an action object used to set block categories.

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

@@ -158,9 +158,7 @@ export default compose( [
 			hasInserterItems,
 			__experimentalGetAllowedBlocks,
 		} = select( 'core/block-editor' );
-		const { __experimentalGetBlockVariations: getBlockVariations } = select(
-			'core/blocks'
-		);
+		const { getBlockVariations } = select( 'core/blocks' );
 
 		rootClientId =
 			rootClientId || getBlockRootClientId( clientId ) || undefined;

packages/block-library/src/columns/edit.js

@@ -218,21 +218,18 @@ const ColumnsEdit = ( props ) => {
 	} = useSelect(
 		( select ) => {
 			const {
-				__experimentalGetBlockVariations,
+				getBlockVariations,
 				getBlockType,
-				__experimentalGetDefaultBlockVariation,
+				getDefaultBlockVariation,
 			} = select( 'core/blocks' );
 
 			return {
 				blockType: getBlockType( name ),
-				defaultVariation: __experimentalGetDefaultBlockVariation(
-					name,
-					'block'
-				),
+				defaultVariation: getDefaultBlockVariation( name, 'block' ),
 				hasInnerBlocks:
 					select( 'core/block-editor' ).getBlocks( clientId ).length >
 					0,
-				variations: __experimentalGetBlockVariations( name, 'block' ),
+				variations: getBlockVariations( name, 'block' ),
 			};
 		},
 		[ clientId, name ]

packages/blocks/README.md

@@ -660,6 +660,15 @@ _Returns_
 
 -   `?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`.
 
+<a name="registerBlockVariation" href="#registerBlockVariation">#</a> **registerBlockVariation**
+
+Registers a new block variation for the given block type.
+
+_Parameters_
+
+-   _blockName_ `string`: Name of the block (example: “core/columns”).
+-   _variation_ `WPBlockVariation`: Object describing a block variation.
+
 <a name="serialize" href="#serialize">#</a> **serialize**
 
 Takes a block or set of blocks and returns the serialized post content.
@@ -765,6 +774,15 @@ _Returns_
 
 -   `?WPBlock`: The previous block value, if it has been successfully unregistered; otherwise `undefined`.
 
+<a name="unregisterBlockVariation" href="#unregisterBlockVariation">#</a> **unregisterBlockVariation**
+
+Unregisters a block variation defined for the given block type.
+
+_Parameters_
+
+-   _blockName_ `string`: Name of the block (example: “core/columns”).
+-   _variationName_ `string`: Name of the variation defined for the block.
+
 <a name="updateCategory" href="#updateCategory">#</a> **updateCategory**
 
 Updates a category.

packages/blocks/src/api/index.js

@@ -50,8 +50,8 @@ export {
 	unstable__bootstrapServerSideBlockDefinitions, // eslint-disable-line camelcase
 	registerBlockStyle,
 	unregisterBlockStyle,
-	__experimentalRegisterBlockVariation,
-	__experimentalUnregisterBlockVariation,
+	registerBlockVariation,
+	unregisterBlockVariation,
 } from './registration';
 export {
 	isUnmodifiedDefaultBlock,

packages/blocks/src/api/registration.js

@@ -491,33 +491,21 @@ export const unregisterBlockStyle = ( blockName, styleVariationName ) => {
 };
 
 /**
- * Registers a new block variation for the given block.
+ * Registers a new block variation for the given block type.
  *
  * @param {string}           blockName Name of the block (example: “core/columns”).
  * @param {WPBlockVariation} variation Object describing a block variation.
  */
-export const __experimentalRegisterBlockVariation = (
-	blockName,
-	variation
-) => {
-	dispatch( 'core/blocks' ).__experimentalAddBlockVariations(
-		blockName,
-		variation
-	);
+export const registerBlockVariation = ( blockName, variation ) => {
+	dispatch( 'core/blocks' ).addBlockVariations( blockName, variation );
 };
 
 /**
- * Unregisters a block variation defined for the given block.
+ * Unregisters a block variation defined for the given block type.
  *
  * @param {string} blockName     Name of the block (example: “core/columns”).
  * @param {string} variationName Name of the variation defined for the block.
  */
-export const __experimentalUnregisterBlockVariation = (
-	blockName,
-	variationName
-) => {
-	dispatch( 'core/blocks' ).__experimentalRemoveBlockVariations(
-		blockName,
-		variationName
-	);
+export const unregisterBlockVariation = ( blockName, variationName ) => {
+	dispatch( 'core/blocks' ).removeBlockVariations( blockName, variationName );
 };

packages/blocks/src/store/actions.js

@@ -73,7 +73,7 @@ export function removeBlockStyles( blockName, styleNames ) {
  *
  * @return {Object} Action object.
  */
-export function __experimentalAddBlockVariations( blockName, variations ) {
+export function addBlockVariations( blockName, variations ) {
 	return {
 		type: 'ADD_BLOCK_VARIATIONS',
 		variations: castArray( variations ),
@@ -89,10 +89,7 @@ export function __experimentalAddBlockVariations( blockName, variations ) {
  *
  * @return {Object} Action object.
  */
-export function __experimentalRemoveBlockVariations(
-	blockName,
-	variationNames
-) {
+export function removeBlockVariations( blockName, variationNames ) {
 	return {
 		type: 'REMOVE_BLOCK_VARIATIONS',
 		variationNames: castArray( variationNames ),

packages/blocks/src/store/selectors.js

@@ -44,10 +44,7 @@ export const getBlockTypes = createSelector(
 		return Object.values( state.blockTypes ).map( ( blockType ) => {
 			return {
 				...blockType,
-				variations: __experimentalGetBlockVariations(
-					state,
-					blockType.name
-				),
+				variations: getBlockVariations( state, blockType.name ),
 			};
 		} );
 	},
@@ -87,7 +84,7 @@ export function getBlockStyles( state, name ) {
  *
  * @return {(WPBlockVariation[]|void)} Block variations.
  */
-export function __experimentalGetBlockVariations( state, blockName, scope ) {
+export function getBlockVariations( state, blockName, scope ) {
 	const variations = state.blockVariations[ blockName ];
 	if ( ! variations || ! scope ) {
 		return variations;
@@ -109,16 +106,8 @@ export function __experimentalGetBlockVariations( state, blockName, scope ) {
  *
  * @return {?WPBlockVariation} The default block variation.
  */
-export function __experimentalGetDefaultBlockVariation(
-	state,
-	blockName,
-	scope
-) {
-	const variations = __experimentalGetBlockVariations(
-		state,
-		blockName,
-		scope
-	);
+export function getDefaultBlockVariation( state, blockName, scope ) {
+	const variations = getBlockVariations( state, blockName, scope );
 
 	return findLast( variations, 'isDefault' ) || first( variations );
 }

packages/blocks/src/store/test/actions.js

@@ -1,10 +1,7 @@
 /**
  * Internal dependencies
  */
-import {
-	__experimentalAddBlockVariations,
-	__experimentalRemoveBlockVariations,
-} from '../actions';
+import { addBlockVariations, removeBlockVariations } from '../actions';
 
 describe( 'actions', () => {
 	describe( 'addBlockVariations', () => {
@@ -19,10 +16,7 @@ describe( 'actions', () => {
 					example: 'foo',
 				},
 			};
-			const result = __experimentalAddBlockVariations(
-				blockName,
-				variation
-			);
+			const result = addBlockVariations( blockName, variation );
 			expect( result ).toEqual( {
 				type: 'ADD_BLOCK_VARIATIONS',
 				variations: [ variation ],
@@ -31,10 +25,7 @@ describe( 'actions', () => {
 		} );
 
 		it( 'should return the REMOVE_BLOCK_VARIATIONS action', () => {
-			const result = __experimentalRemoveBlockVariations(
-				blockName,
-				variationName
-			);
+			const result = removeBlockVariations( blockName, variationName );
 			expect( result ).toEqual( {
 				type: 'REMOVE_BLOCK_VARIATIONS',
 				variationNames: [ variationName ],

packages/blocks/src/store/test/reducer.js

@@ -7,9 +7,9 @@ import deepFreeze from 'deep-freeze';
  * Internal dependencies
  */
 import {
-	__experimentalAddBlockVariations,
+	addBlockVariations,
 	addBlockTypes,
-	__experimentalRemoveBlockVariations,
+	removeBlockVariations,
 } from '../actions';
 import {
 	blockVariations,
@@ -153,7 +153,7 @@ describe( 'blockVariations', () => {
 
 		const state = blockVariations(
 			initialState,
-			__experimentalAddBlockVariations( blockName, blockVariation )
+			addBlockVariations( blockName, blockVariation )
 		);
 
 		expect( state ).toEqual( {
@@ -168,7 +168,7 @@ describe( 'blockVariations', () => {
 
 		const state = blockVariations(
 			initialState,
-			__experimentalAddBlockVariations( blockName, secondBlockVariation )
+			addBlockVariations( blockName, secondBlockVariation )
 		);
 
 		expect( state ).toEqual( {
@@ -201,7 +201,7 @@ describe( 'blockVariations', () => {
 
 		const state = blockVariations(
 			initialState,
-			__experimentalRemoveBlockVariations( blockName, blockVariationName )
+			removeBlockVariations( blockName, blockVariationName )
 		);
 
 		expect( state ).toEqual( {

packages/blocks/src/store/test/selectors.js

@@ -8,7 +8,7 @@ import deepFreeze from 'deep-freeze';
  */
 import {
 	getChildBlockNames,
-	__experimentalGetDefaultBlockVariation,
+	getDefaultBlockVariation,
 	getGroupingBlockName,
 	isMatchingSearchTerm,
 } from '../selectors';
@@ -156,7 +156,7 @@ describe( 'selectors', () => {
 		} );
 	} );
 
-	describe( '__experimentalGetDefaultBlockVariation', () => {
+	describe( 'getDefaultBlockVariation', () => {
 		const blockName = 'block/name';
 		const createBlockVariationsState = ( variations ) => {
 			return deepFreeze( {
@@ -186,10 +186,7 @@ describe( 'selectors', () => {
 				thirdBlockVariation,
 			] );
 
-			const result = __experimentalGetDefaultBlockVariation(
-				state,
-				blockName
-			);
+			const result = getDefaultBlockVariation( state, blockName );
 
 			expect( result ).toEqual( defaultBlockVariation );
 		} );
@@ -211,10 +208,7 @@ describe( 'selectors', () => {
 				defaultBlockVariation,
 			] );
 
-			const result = __experimentalGetDefaultBlockVariation(
-				state,
-				blockName
-			);
+			const result = getDefaultBlockVariation( state, blockName );
 
 			expect( result ).toEqual( defaultBlockVariation );
 		} );
@@ -226,10 +220,7 @@ describe( 'selectors', () => {
 				thirdBlockVariation,
 			] );
 
-			const result = __experimentalGetDefaultBlockVariation(
-				state,
-				blockName
-			);
+			const result = getDefaultBlockVariation( state, blockName );
 
 			expect( result ).toEqual( firstBlockVariation );
 		} );