diff --git a/docs/designers-developers/developers/data/data-core-blocks.md b/docs/designers-developers/developers/data/data-core-blocks.md
index 50a9e8891231b..933c432cd9326 100644
--- a/docs/designers-developers/developers/data/data-core-blocks.md
+++ b/docs/designers-developers/developers/data/data-core-blocks.md
@@ -59,6 +59,20 @@ _Returns_
- `Array`: Block Types.
+# **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|void)`: Block variations.
+
# **getCategories**
Returns all the available categories.
@@ -108,6 +122,23 @@ _Returns_
- `?string`: Default block name.
+# **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.
+
# **getFreeformFallbackBlockName**
Returns the name of the block for handling non-block content.
@@ -246,6 +277,19 @@ _Returns_
- `Object`: Action object.
+# **addBlockVariations**
+
+Returns an action object used in signalling that new block variations have been added.
+
+_Parameters_
+
+- _blockName_ `string`: Block name.
+- _variations_ `(WPBlockVariation|Array)`: Block variations.
+
+_Returns_
+
+- `Object`: Action object.
+
# **removeBlockCollection**
Returns an action object used to remove block collections
@@ -283,6 +327,19 @@ _Returns_
- `Object`: Action object.
+# **removeBlockVariations**
+
+Returns an action object used in signalling that block variations have been removed.
+
+_Parameters_
+
+- _blockName_ `string`: Block name.
+- _variationNames_ `(string|Array)`: Block variation names.
+
+_Returns_
+
+- `Object`: Action object.
+
# **setCategories**
Returns an action object used to set block categories.
diff --git a/packages/block-editor/src/components/inserter/index.js b/packages/block-editor/src/components/inserter/index.js
index 34a430a04545f..11f07899494b4 100644
--- a/packages/block-editor/src/components/inserter/index.js
+++ b/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;
diff --git a/packages/block-library/src/columns/edit.js b/packages/block-library/src/columns/edit.js
index 98c4aac327c6c..b0eb2b9adc14e 100644
--- a/packages/block-library/src/columns/edit.js
+++ b/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 ]
diff --git a/packages/blocks/README.md b/packages/blocks/README.md
index 8fe5c540c229c..2f78d4d7c2e29 100644
--- a/packages/blocks/README.md
+++ b/packages/blocks/README.md
@@ -660,6 +660,15 @@ _Returns_
- `?WPBlock`: The block, if it has been successfully registered; otherwise `undefined`.
+# **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.
+
# **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`.
+# **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.
+
# **updateCategory**
Updates a category.
diff --git a/packages/blocks/src/api/index.js b/packages/blocks/src/api/index.js
index 131175c89568e..99c28b08f1802 100644
--- a/packages/blocks/src/api/index.js
+++ b/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,
diff --git a/packages/blocks/src/api/registration.js b/packages/blocks/src/api/registration.js
index eed76a144c459..8975bb1dc0763 100644
--- a/packages/blocks/src/api/registration.js
+++ b/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 );
};
diff --git a/packages/blocks/src/store/actions.js b/packages/blocks/src/store/actions.js
index 0e9038ea6a406..6339db222cf22 100644
--- a/packages/blocks/src/store/actions.js
+++ b/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 ),
diff --git a/packages/blocks/src/store/selectors.js b/packages/blocks/src/store/selectors.js
index d8117af5d8f27..c896128834429 100644
--- a/packages/blocks/src/store/selectors.js
+++ b/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 );
}
diff --git a/packages/blocks/src/store/test/actions.js b/packages/blocks/src/store/test/actions.js
index c439fa9827238..fbe9544df5860 100644
--- a/packages/blocks/src/store/test/actions.js
+++ b/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 ],
diff --git a/packages/blocks/src/store/test/reducer.js b/packages/blocks/src/store/test/reducer.js
index 3316964743812..55d77ec74f421 100644
--- a/packages/blocks/src/store/test/reducer.js
+++ b/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( {
diff --git a/packages/blocks/src/store/test/selectors.js b/packages/blocks/src/store/test/selectors.js
index 72bcf0c9ecd7e..8ee2fd064bbff 100644
--- a/packages/blocks/src/store/test/selectors.js
+++ b/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 );
} );