(Related design explorations for Block Patterns #17335.)

Description

A lot of block use the "setup state" pattern where some options/layouts are shown to the block user while inserterting the block:

• The Columns block shows a number of layouts
• The table block shows a setup state to choose rows and columns
• The Cover block could benefit from a similar "initial layouts" state
• A number of third party blocks use that pattern as well.

All these are similar in behavior. The user picks a variation and this variation applies initial attributes and innerBlocks content to the selected block.

The idea of this issue is to generalize that concept. Similarily to how we define block style variations, a block type should be able to define Block Variations the user could pick from.

API

The API could look something like this:

const blockTypeSettings = {
   // ...
   variations: [
       { name: __( 'Two columns; equal split' ), innerBlocks: [ ['core/column'], ['core/column'] ] },
       { name: __( 'Three columns; equal split' ), innerBlocks: [ ['core/column'], ['core/column'], ['core/column'] ] },
   ]

The variations can also define just attributes

 // ...
   variations: [
       { name: __( 'Big Quote' ), attributes: { size:'big' } },
       { name: __( 'Small Quote' ), attributes: { size:'small' } },
   ]

These are just examples to illustrate the API and not a final design.

We'd also probably need APIs to register/unregister these variations (similar to the style variations).

UI

In terms of UI, we could explore different possibilities:

• Offer these variations as a setup state (Like a placeholder that shows up when you insert the block)
• Offer these variations in the "Block Switcher" dropdown
• Offer these variations in the inspector panel

Related #16129

Current Tasks

1. Create an API for registering variations very close to block styles (Blocks: Add initial API for Block Variations (formerly Patterns) #18270).
2. Refactor Columns block to use this new API making the placeholder open for customization (Block Library: Update Columns block to use Patterns API #18283).
3. Refactor more blocks that fit like:
   • Media+Text (Block library: Patterns API integration with Media & Text block #18343) – closed as UX wasn't great
   • Table – it doesn't seem to be a good idea
   • Cover – it doesn't seem to be a good idea
4. Explore how we can modify the search logic in the inserter to match blocks through variations as proposed by @kjellr (Blocks: Match blocks in the inserter using keywords from patterns #19243).
5. Rename the API from patterns to variations (Blocks: Rename patterns to variations in the Block API #19966).
6. Blocks: Promote block variations to stable API (Blocks: Promote block variations to stable API #20068).
7. Add three e2e tests that use example scenarios listed in the description of Blocks: Promote block variations to stable API #20068 (E2E tests: Block variations #20286).
8. Block API docs should be updated to include details about this new API (Docs: Add docs for variations in the block registration section #20145).
9. Adding a tutorial for users would be fantastic.
10. Extract common logic as an initial screen for blocks that define variations.
11. Integrate variations with the / inserter.
12. Explore how it could be embedded in the block inspector.
13. Explore how blocks could inform about the variation applied.