[Docs]: Update block variations documentation about block scope

docs/reference-guides/block-api/block-variations.md

@@ -45,7 +45,7 @@ An object describing a variation defined for the block type can contain the foll
 -   `example` (optional, type `Object`) – Example provides structured data for the block preview. You can set to `undefined` to disable the preview shown for the block type.
 -   `scope` (optional, type `WPBlockVariationScope[]`) - the list of scopes where the variation is applicable. When not provided, it defaults to `block` and `inserter`. Available options:
     -   `inserter` - Block Variation is shown on the inserter.
-    -   `block` - Used by blocks to filter specific block variations. Mostly used in Placeholder patterns like `Columns` block.
+    -   `block` - Used by blocks to filter specific block variations. `Columns` and `Query Loop` blocks have such variations and are passed to the [experimental BlockVariationPicker](/packages/block-editor/src/components/block-variation-picker/README.md) component, which is handling the displaying of variations and the ability to select one from them.
     -   `transform` - Block Variation will be shown in the component for Block Variations transformations.
 -   `keywords` (optional, type `string[]`) - An array of terms (which can be translated) that help users discover the variation while searching.
 -   `isActive` (optional, type `Function|string[]`) - This can be a function or an array of block attributes. Function that accepts a block's attributes and the variation's attributes and determines if a variation is active. This function doesn't try to find a match dynamically based on all block's attributes, as in many cases some attributes are irrelevant. An example would be for `embed` block where we only care about `providerNameSlug` attribute's value. We can also use a `string[]` to tell which attributes should be compared as a shorthand. Each attributes will be matched and the variation will be active if all of them are matching.

packages/block-editor/src/components/block-variation-picker/README.md

@@ -1,8 +1,12 @@
 # Block Variation Picker
 
-The `BlockVariationPicker` component allows to display for certain types of blocks their different variations, and to choose one of them.
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
 
-This component is currently used by the "Columns" block to display and choose the number and structure of columns. It is also used by the "Post Hierarchical Terms Block" block.
+The `BlockVariationPicker` component allows certain types of blocks to display their different variations, and to choose one of them. Variations provided are usually filtered by their inclusion of the `block` value in their `scope` attribute.
+
+This component is currently used by "Columns" and "Query Loop" blocks.
 
 ![Columns block variations](https://make.wordpress.org/core/files/2020/09/colums-block-variations.png)
 
@@ -18,33 +22,62 @@ This component is currently used by the "Columns" block to display and choose th
 Renders the variations of a block.
 
 ```jsx
-import { BlockVariationPicker } from '@wordpress/block-editor';
-
-const MyBlockVariationPicker = () => (
-	<BlockVariationPicker variations={ variations } />
-);
+import { useSelect } from '@wordpress/data';
+import {
+	__experimentalBlockVariationPicker as BlockVariationPicker,
+	store as blockEditorStore,
+} from '@wordpress/block-editor';
+
+const MyBlockVariationPicker = ( { blockName } ) => {
+	const variations = useSelect(
+		( select ) => {
+			const { getBlockVariations } = select( blocksStore );
+			return getBlockVariations( blockName, 'block' );
+		},
+		[ blockName ]
+	);
+	return <BlockVariationPicker variations={ variations } />;
+};
 ```
 
 ### Props
 
-#### label
-
-The label of each variation of the block.
+#### `label`
 
 -   Type: `String`
+-   Required: No
+-   Default: `Choose variation`
 
-#### instructions
+The label of each variation of the block.
 
-The instructions to choose a block variation.
+#### `instructions`
 
 -   Type: `String`
+-   Required: No
+-   Default: `Select a variation to start with.`
+
+The instructions to choose a block variation.
 
-#### variations
+#### `variations`
 
--   Type: `Array`
+-   Type: `Array<WPBlockVariation>`
 
 The different variations of the block.
 
+#### `onSelect`
+
+-   Type: `Function`
+
+Callback called when a block variation is selected. It recieves the selected variation as a parameter.
+
+#### `icon`
+
+-   Type: `Icon component`
+-   Required: No
+-   Default: `layout`
+
+Icon to be displayed at the top of the component before the `label`.
+
 ## Related components
 
 Block Editor components are components that can be used to compose the UI of your block editor. Thus, they can only be used under a [BlockEditorProvider](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/provider/README.md) in the components tree.