Improvements to active block variation detection

WordPress 6.6 includes improvements to how a block variation is detected as active for a given blockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. via the variation’s isActive property. This property can be either a function (that compares block and variation attributes), or a string[] shorthand that specifies which of the variation’s attributes to consider when comparing them to the block’s. The following changes affect only the string[] shorthand, which is now generally recommended over the function version.

Dot notation

Block variations can now use dot notation for “object paths” to specify “nested” attributes in their isActive property. For example, if a block’s query attribute is an object, it is now possible to use the following shorthand notation for isActive to determine if a variation is active based on the query object’s postType property:

attributes: {
    query: {
        postType: 'post',
        order: 'desc',
        orderBy: 'date',
    },
},
isActive: [ 'query.postType' ]

This was previously only possible by using an isActive function:

isActive: ( blockAttributes, variationAttributes ) => {
    return blockAttributes.query.postType === variationAttributes.query.postType;
}

Highest specificity wins

If multiple variations have an isActive string array property that matches a given block, getActiveBlockVariation() will now return the one with the highest specificity. For example, take two variations of the same block, one with

attributes: {
    textColor: 'vivid-red',
},
isActive: [ 'textColor' ],

and another with

attributes: {
    textColor: 'vivid-red',
    backgroundColor: 'cyan-bluish-gray'
},
isActive: [ 'textColor', 'backgroundColor' ]

Now 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 specificity of each match will be calculated as the length of each isActive array, and the matching variation with the highest specificity will be returned — in this example, the second one.

Comparison of objects

If an isActive array item is an object, it was previously compared by reference. This has been fixed such that a block is considered to match a variation if it contains all the properties that the variation specifies for that object and if the properties have the same values. For example, the following variation

attributes: {
    query: {
        postType: 'post',
        order: 'desc',
        orderBy: 'date',
    },
},
isActive: [ 'query' ]

matches a block with its query attribute set to

{
    postType: 'post',
    order: 'desc',
    orderBy: 'date',
    offset: 10,
}

But it doesn’t match

    postType: 'post',
    order: 'desc',
    offset: 10,

as the orderBy property that’s specified by the variation is missing.

Comparison of RichText

Finally, rich-text attributes are now compared correctly when used in a block variation’s isActive array. For example:

<pre class="wp-block-syntaxhighlighter-code">attributes: {
    content: 'This is a <strong>warning</strong> message.',
},
isActive: [ 'content' ]</pre>

Conclusion

We hope that these improvements will make developers’ lives easier when working with block variations. They’re also meant to lay the foundations for some other enhancements we’re planning to make to block variations during the next cycle (e.g., automatically added class names for variations, or variation aliases).

Props to @bph and @juanmaguitar for review