Block variations: Add block-supports flag to add variation specific classname

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

@@ -176,8 +176,11 @@ attributes: {
 
 ## className
 
--   Type: `boolean`
+-   Type: `boolean` or `Object`
 -   Default value: `true`
+-   Subproperties:
+    -   `block`: type `boolean`, default value `true`
+    -   `variation`: type `boolean`, default value `false`
 
 By default, the class `.wp-block-your-block-name` is added to the root element of your saved markup. This helps by providing a consistent mechanism for styling blocks that themes and plugins can rely on. If, for whatever reason, a class is not desired on the markup, this functionality can be disabled.
 
@@ -188,6 +191,32 @@ supports: {
 }
 ```
 
+### className.block
+
+The above is equivalent to the more verbose
+
+```js
+supports: {
+	// Remove the support for the generated className.
+	className: {
+		block: false
+	}
+}
+```
+
+### className.variation
+
+In the same vein, it is possible to have a variation-specific class added to a block (if the latter supports variations). E.g. if a block named `your/block-name` has a variation called `your-variation`, the following will add the class `.wp-block-your-block-name__your-variation`:
+
+```js
+supports: {
+	// Add block variation-specific className.
+	className: {
+		variation: true
+	}
+}
+```
+
 ## color
 
 -   Type: `Object`

docs/reference-guides/filters/block-filters.md

@@ -270,7 +270,7 @@ To avoid this validation error, use `render_block` server-side to modify existin
 
 ### `blocks.getBlockDefaultClassName`
 
-Generated HTML classes for blocks follow the `wp-block-{name}` nomenclature. This filter allows to provide an alternative class name.
+[Generated HTML classes for blocks](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#classname) follow the `wp-block-{name}` nomenclature. This filter allows to provide an alternative class name.
 
 ```js
 // Our filter function.
@@ -286,6 +286,8 @@ wp.hooks.addFilter(
 );
 ```
 
+If a block has opted into [block support for generated block _variation_ specific class names](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#classname), the filter also affects those. With the above example, if the `core/code` block has a `php` variation, it would get `my-plugin-code-php` as its variation specific class name (instead of the default `wp-block-code-php`).
+
 ### `blocks.switchToBlockType.transformedBlock`
 
 Used to filter an individual transform result from block transformation. All of the original blocks are passed since transformations are many-to-many, not one-to-one.

packages/block-editor/src/components/block-edit/edit.js

@@ -9,7 +9,7 @@ import clsx from 'clsx';
 import { withFilters } from '@wordpress/components';
 import {
 	getBlockDefaultClassName,
-	hasBlockSupport,
+	getBlockVariationClassName,
 	getBlockType,
 } from '@wordpress/blocks';
 import { useContext, useMemo } from '@wordpress/element';
@@ -18,6 +18,10 @@ import { useContext, useMemo } from '@wordpress/element';
  * Internal dependencies
  */
 import BlockContext from '../block-context';
+import {
+	hasBlockClassNameSupport,
+	hasVariationClassNameSupport,
+} from '../../hooks/supports';
 
 /**
  * Default value used for blocks which do not define their own context needs,
@@ -71,12 +75,23 @@ const EditWithGeneratedProps = ( props ) => {
 		return <EditWithFilters { ...props } context={ context } />;
 	}
 
-	// Generate a class name for the block's editable form.
-	const generatedClassName = hasBlockSupport( blockType, 'className', true )
-		? getBlockDefaultClassName( name )
-		: null;
+	const generatedClassNames = [];
+
+	if ( hasBlockClassNameSupport( blockType ) ) {
+		generatedClassNames.push( getBlockDefaultClassName( name ) );
+	}
+	if ( hasVariationClassNameSupport( blockType ) ) {
+		const variationClassName = getBlockVariationClassName(
+			blockType.name,
+			attributes
+		);
+		if ( variationClassName ) {
+			generatedClassNames.push( variationClassName );
+		}
+	}
+
 	const className = clsx(
-		generatedClassName,
+		generatedClassNames,
 		attributes.className,
 		props.className
 	);

packages/block-editor/src/components/block-edit/test/edit.js

@@ -84,6 +84,49 @@ describe( 'Edit', () => {
 		expect( editElement ).toHaveClass( 'my-class' );
 	} );
 
+	it( 'should combine the default class name with a variation one', () => {
+		const edit = ( { className } ) => (
+			<div data-testid="foo-bar" className={ className } />
+		);
+
+		registerBlockType( 'core/test-block', {
+			edit,
+			save: noop,
+			category: 'text',
+			title: 'block title',
+			attributes: {
+				fruit: {
+					type: 'string',
+					default: 'Apples',
+				},
+			},
+			supports: {
+				className: {
+					block: true,
+					variation: true,
+				},
+			},
+			variations: [
+				{
+					name: 'variation',
+					title: 'block variation title',
+					attributes: {
+						fruit: 'Bananas',
+					},
+					isActive: [ 'fruit' ],
+				},
+			],
+		} );
+
+		render(
+			<Edit name="core/test-block" attributes={ { fruit: 'Bananas' } } />
+		);
+
+		const editElement = screen.getByTestId( 'foo-bar' );
+		expect( editElement ).toHaveClass( 'wp-block-test-block' );
+		expect( editElement ).toHaveClass( 'wp-block-test-block__variation' );
+	} );
+
 	it( 'should assign context', () => {
 		const edit = ( { context } ) => context.value;
 		registerBlockType( 'core/test-block', {

packages/block-editor/src/components/block-list/block.js

@@ -23,6 +23,7 @@ import {
 	isUnmodifiedBlock,
 	isReusableBlock,
 	getBlockDefaultClassName,
+	getBlockVariationClassName,
 	hasBlockSupport,
 	store as blocksStore,
 } from '@wordpress/blocks';
@@ -43,6 +44,7 @@ import { useBlockProps } from './use-block-props';
 import { store as blockEditorStore } from '../../store';
 import { useLayout } from './layout';
 import { PrivateBlockContext } from './private-block-context';
+import { hasVariationClassNameSupport } from '../../hooks/supports';
 
 import { unlock } from '../../lock-unlock';
 
@@ -592,12 +594,27 @@ function BlockListBlockProvider( props ) {
 				hasBlockSupport: _hasBlockSupport,
 				getActiveBlockVariation,
 			} = select( blocksStore );
+
 			const attributes = getBlockAttributes( clientId );
 			const { name: blockName, isValid } = blockWithoutAttributes;
 			const blockType = getBlockType( blockName );
 			const { supportsLayout, __unstableIsPreviewMode: isPreviewMode } =
 				getSettings();
 			const hasLightBlockWrapper = blockType?.apiVersion > 1;
+			const defaultClassNames = [];
+			if ( hasLightBlockWrapper ) {
+				defaultClassNames.push( getBlockDefaultClassName( blockName ) );
+
+				if ( hasVariationClassNameSupport( blockType ) ) {
+					const variationClassName = getBlockVariationClassName(
+						blockType.name,
+						attributes
+					);
+					if ( variationClassName ) {
+						defaultClassNames.push( variationClassName );
+					}
+				}
+			}
 			const previewContext = {
 				isPreviewMode,
 				blockWithoutAttributes,
@@ -610,9 +627,10 @@ function BlockListBlockProvider( props ) {
 				className: hasLightBlockWrapper
 					? attributes.className
 					: undefined,
-				defaultClassName: hasLightBlockWrapper
-					? getBlockDefaultClassName( blockName )
-					: undefined,
+				defaultClassName:
+					defaultClassNames.length > 0
+						? clsx( defaultClassNames )
+						: undefined,
 				blockTitle: blockType?.title,
 			};
 
@@ -625,7 +643,6 @@ function BlockListBlockProvider( props ) {
 			const _isSelected = isBlockSelected( clientId );
 			const canRemove = canRemoveBlock( clientId );
 			const canMove = canMoveBlock( clientId );
-			const match = getActiveBlockVariation( blockName, attributes );
 			const isMultiSelected = isBlockMultiSelected( clientId );
 			const checkDeep = true;
 			const isAncestorOfSelectedBlock = hasSelectedInnerBlock(
@@ -635,6 +652,8 @@ function BlockListBlockProvider( props ) {
 			const movingClientId = hasBlockMovingClientId();
 			const blockEditingMode = getBlockEditingMode( clientId );
 
+			const match = getActiveBlockVariation( blockName, attributes );
+
 			const multiple = hasBlockSupport( blockName, 'multiple', true );
 
 			// For block types with `multiple` support, there is no "original

packages/block-editor/src/hooks/generated-class-name.js

@@ -2,7 +2,18 @@
  * WordPress dependencies
  */
 import { addFilter } from '@wordpress/hooks';
-import { hasBlockSupport, getBlockDefaultClassName } from '@wordpress/blocks';
+import {
+	getBlockDefaultClassName,
+	getBlockVariationClassName,
+} from '@wordpress/blocks';
+
+/**
+ * Internal dependencies
+ */
+import {
+	hasBlockClassNameSupport,
+	hasVariationClassNameSupport,
+} from '../hooks/supports';
 
 /**
  * Override props assigned to save component to inject generated className if
@@ -11,30 +22,46 @@ import { hasBlockSupport, getBlockDefaultClassName } from '@wordpress/blocks';
  *
  * @param {Object} extraProps Additional props applied to save element.
  * @param {Object} blockType  Block type.
+ * @param {Object} attributes Block attributes.
  *
  * @return {Object} Filtered props applied to save element.
  */
-export function addGeneratedClassName( extraProps, blockType ) {
-	// Adding the generated className.
-	if ( hasBlockSupport( blockType, 'className', true ) ) {
-		if ( typeof extraProps.className === 'string' ) {
-			// We have some extra classes and want to add the default classname
-			// We use uniq to prevent duplicate classnames.
-
-			extraProps.className = [
-				...new Set( [
-					getBlockDefaultClassName( blockType.name ),
-					...extraProps.className.split( ' ' ),
-				] ),
-			]
-				.join( ' ' )
-				.trim();
-		} else {
-			// There is no string in the className variable,
-			// so we just dump the default name in there.
-			extraProps.className = getBlockDefaultClassName( blockType.name );
+export function addGeneratedClassName( extraProps, blockType, attributes ) {
+	const generatedClassNames = [];
+	if ( hasBlockClassNameSupport( blockType ) ) {
+		generatedClassNames.push( getBlockDefaultClassName( blockType.name ) );
+	}
+	if ( hasVariationClassNameSupport( blockType ) ) {
+		const variationClassName = getBlockVariationClassName(
+			blockType.name,
+			attributes
+		);
+		if ( variationClassName ) {
+			generatedClassNames.push( variationClassName );
 		}
 	}
+
+	if ( generatedClassNames.length === 0 ) {
+		return extraProps;
+	}
+
+	if ( typeof extraProps.className === 'string' ) {
+		// We have some extra classes and want to add the default classname
+		// We use a Set to prevent duplicate classnames.
+		extraProps.className = [
+			...new Set( [
+				...generatedClassNames,
+				...extraProps.className.split( ' ' ),
+			] ),
+		]
+			.join( ' ' )
+			.trim();
+	} else {
+		// There is no string in the className variable,
+		// so we just dump the default name(s) in there.
+		extraProps.className = generatedClassNames.join( ' ' );
+	}
+
 	return extraProps;
 }
 

packages/block-editor/src/hooks/supports.js

@@ -339,3 +339,33 @@ export const getLayoutSupport = ( nameOrType ) =>
  */
 export const hasStyleSupport = ( nameOrType ) =>
 	styleSupportKeys.some( ( key ) => hasBlockSupport( nameOrType, key ) );
+
+/**
+ * Returns true if the block defines support for block class name.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasBlockClassNameSupport = ( nameOrType ) => {
+	const classNameSupport = getBlockSupport( nameOrType, 'className', true );
+
+	if ( typeof classNameSupport === 'boolean' ) {
+		return classNameSupport;
+	}
+
+	// classNameSupport can be an object. If it doesn't have a `block` key,
+	// we default to true.
+	return (
+		! Object.hasOwn( classNameSupport, 'block' ) ||
+		classNameSupport.block === true
+	);
+};
+
+/**
+ * Returns true if the block defines support for variation class name.
+ *
+ * @param {string|Object} nameOrType Block name or type object.
+ * @return {boolean} Whether the block supports the feature.
+ */
+export const hasVariationClassNameSupport = ( nameOrType ) =>
+	hasBlockSupport( nameOrType, 'className.variation', false );