Docs: Explicitly mention new behavior coming in WP 6.6 for block vari…

…ations (#62399)

Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: fabiankaegy <fabiankaegy@git.wordpress.org>
Co-authored-by: ockham <bernhard-reiter@git.wordpress.org>

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

@@ -1,12 +1,11 @@
 # Variations
 
-The Block Variations API  allows you to define multiple versions (variations) of a block. A block variation differs from the original block by a set of initial attributes or inner blocks. When you insert the block variation into the Editor, these attributes and/or inner blocks are applied.
+The Block Variations API allows you to define multiple versions (variations) of a block. A block variation differs from the original block by a set of initial attributes or inner blocks. When you insert the block variation into the Editor, these attributes and/or inner blocks are applied.
 
 Variations are an excellent way to create iterations of existing blocks without building entirely new blocks from scratch.
 
 To better understand this API, consider the Embed block. This block contains numerous variations for each type of embeddable content (WordPress, Youtube, etc.). Each Embed block variation shares the same underlying functionality for editing, saving, and so on. Besides the name and descriptive information, the main difference is the `providerNameSlug` attribute. Below is a simplified example of the variations in the Embed block. View the [source code](https://github.com/WordPress/gutenberg/blob/trunk/packages/block-library/src/embed/variations.js) for the complete specification.
 
-
 ```js
 variations: [
 	{
@@ -38,7 +37,7 @@ A block variation is defined by an object that can contain the following fields:
 -   `innerBlocks` (optional, type `Array[]`) – Initial configuration of nested blocks.
 -   `example` (optional, type `Object`) – Provides structured data for the block preview. Set to `undefined` to disable the preview. See the [Block Registration API](/docs/reference-guides/block-api/block-registration.md#example-optional) for more details.
 -   `scope` (optional, type `WPBlockVariationScope[]`) - Defaults to `block` and `inserter`. The list of scopes where the variation is applicable. Available options include:
-	- `block` - Used by blocks to filter specific block variations. `Columns` and `Query` blocks have such variations, which are passed to the [experimental BlockVariationPicker](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md) component. This component handles displaying the variations and allows users to choose one of them.
+    -   `block` - Used by blocks to filter specific block variations. `Columns` and `Query` blocks have such variations, which are passed to the [experimental BlockVariationPicker](https://github.com/WordPress/gutenberg/blob/HEAD/packages/block-editor/src/components/block-variation-picker/README.md) component. This component handles displaying the variations and allows users to choose one of them.
     -   `inserter` - Block variation is shown on the inserter.
     -   `transform` - Block variation is shown in the component for variation transformations.
 -   `isDefault` (optional, type `boolean`) – Defaults to `false`. Indicates whether the current variation is the default one (details below).
@@ -55,13 +54,10 @@ Block variations can be declared during a block's registration by providing the
 To create a variation for an existing block, such as a Core block, use `wp.blocks.registerBlockVariation()`. This function accepts the name of the block and the object defining the variation.
 
 ```js
-wp.blocks.registerBlockVariation(
-	'core/embed',
-	{
-		name: 'custom-embed',
-		attributes: { providerNameSlug: 'custom' },
-	}
-);
+wp.blocks.registerBlockVariation( 'core/embed', {
+	name: 'custom-embed',
+	attributes: { providerNameSlug: 'custom' },
+} );
 ```
 
 ## Removing a block variation
@@ -102,17 +98,14 @@ By default, all variations will show up in the Inserter in addition to the origi
 For example, if you want Media & Text block to display the image on the right by default, you could create a variation like this:
 
 ```js
- wp.blocks.registerBlockVariation(
-	'core/media-text',
-	{
-		name: 'media-text-media-right',
-		title: __( 'Media & Text' ),
-		isDefault: true,
-		attributes: {
-			mediaPosition: 'right'
-		}
-	}
-)
+wp.blocks.registerBlockVariation( 'core/media-text', {
+	name: 'media-text-media-right',
+	title: __( 'Media & Text' ),
+	isDefault: true,
+	attributes: {
+		mediaPosition: 'right',
+	},
+} );
 ```
 
 ### Caveats to using `isDefault`
@@ -159,21 +152,21 @@ const variations = [
 		attributes: { providerNameSlug: 'youtube', responsive: true },
 	},
 	// ...
-]
+];
 ```
 
 The `isActive` property would then look like this:
 
 ```js
-isActive: [ 'providerNameSlug' ]
+isActive: [ 'providerNameSlug' ];
 ```
 
 This will cause the block instance value for `providerNameSlug` to be compared to the value declared in the variation's declaration (the values in the code snippet above) to determine which embed variation is active.
 
-Nested object paths are also supported. For example, consider a block variation that has a `query` object as an attribute. It is possible to determine if the variation is active solely based on that object's `postType` property (while ignoring all its other properties):
+Nested object paths are also supported since WordPress `6.6.0`. For example, consider a block variation that has a `query` object as an attribute. It is possible to determine if the variation is active solely based on that object's `postType` property (while ignoring all its other properties):
 
 ```js
-isActive: [ 'query.postType' ]
+isActive: [ 'query.postType' ];
 ```
 
 The function version of this property accepts a block instance's `blockAttributes` as the first argument, and the `variationAttributes` declared for a variation as the second argument. These arguments can be used to determine if a variation is active by comparing them and returning a `true` or `false` (indicating whether this variation is inactive for this block instance).
@@ -187,33 +180,29 @@ isActive: ( blockAttributes, variationAttributes ) =>
 
 ### Specificity of `isActive` matches
 
+_Note: Improved handling since WordPress `6.6.0`._
+
 If there are multiple variations whose `isActive` check matches a given block instance, and all of them are string arrays, then the variation with the highest _specificity_ will be chosen. Consider the following example:
 
 ```js
-wp.blocks.registerBlockVariation(
-	'core/paragraph',
-	{
-		name: 'paragraph-red',
-		title: 'Red Paragraph',
-		attributes: {
-			textColor: 'vivid-red',
-		},
-		isActive: [ 'textColor' ],
-	}
-);
-
-wp.blocks.registerBlockVariation(
-	'core/paragraph',
-	{
-		name: 'paragraph-red-grey',
-		title: 'Red/Grey Paragraph',
-		attributes: {
-			textColor: 'vivid-red',
-			backgroundColor: 'cyan-bluish-gray'
-		},
-		isActive: [ 'textColor', 'backgroundColor' ]
-	}
-);
+wp.blocks.registerBlockVariation( 'core/paragraph', {
+	name: 'paragraph-red',
+	title: 'Red Paragraph',
+	attributes: {
+		textColor: 'vivid-red',
+	},
+	isActive: [ 'textColor' ],
+} );
+
+wp.blocks.registerBlockVariation( 'core/paragraph', {
+	name: 'paragraph-red-grey',
+	title: 'Red/Grey Paragraph',
+	attributes: {
+		textColor: 'vivid-red',
+		backgroundColor: 'cyan-bluish-gray',
+	},
+	isActive: [ 'textColor', 'backgroundColor' ],
+} );
 ```
 
 If a block instance has attributes `textColor: vivid-red` and `backgroundColor: cyan-bluish-gray`, both variations' `isActive` criterion will match that block instance. In this case, the more _specific_ match will be determined to be the active variation, where specificity is calculated as the length of each `isActive` array. This means that the `Red/Grey Paragraph` will be shown as the active variation.