Blocks: Promote block variations to stable API

[gziolo]

Description

Part of #16283.

Now that #19887 is close to merging, I opened #20068 to mark the API for the inserter as stable. It also will work with the Columns block.

__experimentalBlockVariationPicker remains experimental.

New APIs

New type definitions

/**
 * Named block variation scopes.
 *
 * @typedef {'block'|'inserter'} WPBlockVariationScope
 */

/**
 * An object describing a variation defined for the block type.
 *
 * @typedef {Object} WPBlockVariation
 *
 * @property {string}   name                   The unique and machine-readable name.
 * @property {string}   title                  A human-readable variation title.
 * @property {string}   description            A detailed variation description.
 * @property {WPIcon}   [icon]                 An icon helping to visualize the variation.
 * @property {boolean}  [isDefault]            Indicates whether the current variation is
 *                                             the default one. Defaults to `false`.
 * @property {Object}   [attributes]           Values which override block attributes.
 * @property {Array[]}  [innerBlocks]          Initial configuration of nested blocks.
 * @property {Object}   [example]              Example provides structured data for
 *                                             the block preview. You can set to
 *                                             `undefined` to disable the preview shown
 *                                             for the block type.
 * @property {WPBlockVariationScope[]} [scope] The list of scopes where the variation
 *                                             is applicable. When not provided, it
 *                                             assumes all available scopes.
 */

@wordpress/blocks

/**
 * Registers a new block variation for the given block.
 *
 * @param {string}           blockName Name of the block (example: “core/columns”).
 * @param {WPBlockVariation} variation Object describing a block variation.
 */
function registerBlockVariation( blockName, variation );

/**
 * Unregisters a block variation defined for the given block.
 *
 * @param {string} blockName     Name of the block (example: “core/columns”).
 * @param {string} variationName Name of the variation defined for the block.
 */
function unregisterBlockVariation( blockName, variationName );

core/blocks store

/**
 * Returns an action object used in signalling that new block variations have been added.
 *
 * @param {string}                              blockName  Block name.
 * @param {WPBlockVariation|WPBlockVariation[]} variations Block variations.
 *
 * @return {Object} Action object.
 */
function addBlockVariations( blockName, variations );

/**
 * Returns an action object used in signalling that block variations have been removed.
 *
 * @param {string}          blockName      Block name.
 * @param {string|string[]} variationNames Block variation names.
 *
 * @return {Object} Action object.
 */
function removeBlockVariations( blockName, variationNames );

/**
 * Returns block variations by block name.
 *
 * @param {Object}                state     Data state.
 * @param {string}                blockName Block type name.
 * @param {WPBlockVariationScope} [scope]   Block variation scope name.
 *
 * @return {(WPBlockVariation[]|void)} Block variations.
 */
function getBlockVariations( state, blockName, scope );

/**
 * 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.
 *
 * @param {Object}                state     Data state.
 * @param {string}                blockName Block type name.
 * @param {WPBlockVariationScope} [scope]   Block variation scope name.
 *
 * @return {?WPBlockVariation} The default block variation.
 */
function getDefaultBlockVariation( state, blockName, scope );

Testing scenarios:

Recorded screencasts contain unstable API but included code examples are up to date.

1. Registers the variation with the inner blocks to apply from the block variation picker using scope limited to the block:

wp.blocks.registerBlockVariation( 'core/columns', { name: 'custom', title: 'Smiley', isDefault: true, innerBlocks: [ [ 'core/column' ], [ 'core/column' ], [ 'core/column' ], [ 'core/column' ] ], icon: 'smiley', scope: [ 'block' ] } );

2. Registers the variation with the inner blocks to apply from the inserter using scope limited to the inserter:

wp.blocks.registerBlockVariation( 'core/columns', { name: 'custom', title: 'Smiley', isDefault: true, innerBlocks: [ [ 'core/column' ], [ 'core/column' ], [ 'core/column' ], [ 'core/column' ] ], icon: 'smiley', scope: [ 'inserter' ] } );

2. Registers two variations with initial attributes to apply from the inserter directly:

wp.blocks.registerBlockVariation( 'core/heading', { name: 'green-text', title: 'Green Text', description: 'This block has green text. It overrides the default description.',  attributes: { content: 'Green Text', textColor: 'vivid-green-cyan' }, icon: 'palmtree', scope: [ 'inserter' ] } );
wp.blocks.registerBlockVariation( 'core/heading', { name: 'red-text', title: 'Red Text', attributes: { content: 'Red Text', level: 3, textColor: 'vivid-red' }, icon: 'smiley', scope: [ 'inserter' ] } );

3. Registers a variation which allows changing the default style variation:

wp.blocks.registerBlockVariation( 'core/quote', { name: 'large', title: 'Large Quote', isDefault: true, attributes: { className: 'is-style-large' }, icon: 'palmtree', scope: [ 'inserter' ] } );

Checklist:

• My code is tested.
• My code follows the WordPress code style.
• My code follows the accessibility standards.
• My code has proper inline documentation.
• I've included developer documentation if appropriate.
• I've updated all React Native files affected by any refactorings/renamings in this PR.

[gziolo]

@jorgefilipecosta, I hope I included enough details to compile the dev note for the release. There are three follow up tasks left for the beta phase, I can work on them after WP 5.4 Beta 1 is out:

• Three e2e tests that use example scenarios listed in the description
• Block API docs should be updated to include details about this new API
• Adding a tutorial for users would be fantastic as well (cc @mkaz and @chrisvanpatten 😄)

I added all 3 items to #16283.

[mtias]

@gziolo great work on this one. I think it's a great case to have some examples in our docs, as it's a way to build "new blocks" with very little effort.

[gziolo]

@gziolo great work on this one. I think it's a great case to have some examples in our docs, as it's a way to build "new blocks" with very little effort.

It's definitely on my todo list for WP 5.4 Beta phase, together with Dev Note :)