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 ); } );