Add Heading level variations (#73823)

Adds h1-h6 as block variations for the heading block

- Heading level shown in sidebar inspector variation picker
- Level-specific icons in the sidebar picker
- Proper variation detection via isActive callbacks

The variations use scope ['block', 'transform'] to appear in the
sidebar picker and transforms, while keeping the inserter clean
with just the base "Heading" block.

Extends the inserter to include block-scope variations in search results,
enabling slash commands like `/h3` to find variations that appear in the
sidebar variation picker.

Author: mtias

packages/block-editor/src/components/block-variation-transforms/index.js

@@ -229,16 +229,13 @@ function __experimentalBlockVariationTransforms( { blockClientId } ) {
 				( v ) => v.name !== 'stretchy-paragraph'
 			);
 		} else if ( blockName === 'core/heading' ) {
-			if (
-				activeBlockVariation?.name === 'stretchy-heading' ||
-				unfilteredVariations.every( ( v ) =>
-					[ 'heading', 'stretchy-heading' ].includes( v.name )
-				)
-			) {
+			// Hide variations picker when stretchy-heading is active.
+			if ( activeBlockVariation?.name === 'stretchy-heading' ) {
 				return [];
 			}
+			// Filter out stretchy-heading.
 			return unfilteredVariations.filter(
-				( v ) => v.name !== 'stretchy-heading'
+				( variation ) => variation.name !== 'stretchy-heading'
 			);
 		}
 		return unfilteredVariations;

packages/block-editor/src/components/block-variation-transforms/style.scss

@@ -6,10 +6,10 @@
 	padding: 0 $grid-unit-20 $grid-unit-20 52px;
 
 	&:where(fieldset) {
-		// Reset `fieldset` browser defaults.
+		// Reset `fieldset` browser defaults, keeping intentional padding.
 		border: 0;
-		padding: 0;
 		margin: 0;
+		min-inline-size: 0;
 	}
 }
 

packages/block-editor/src/components/inserter/block-types-tab.js

@@ -186,6 +186,11 @@ export function BlockTypesTab(
 			continue;
 		}
 
+		// Skip search-only items from browse view (they're still searchable).
+		if ( item.isSearchOnly ) {
+			continue;
+		}
+
 		if ( item.isAllowedInCurrentRoot ) {
 			itemsForCurrentRoot.push( item );
 		} else {

packages/block-editor/src/store/selectors.js

@@ -2078,6 +2078,8 @@ const getItemFromVariation = ( state, item ) => ( variation ) => {
 		innerBlocks: variation.innerBlocks,
 		keywords: variation.keywords || item.keywords,
 		frecency: calculateFrecency( time, count ),
+		// Pass through search-only flag for block-scope variations.
+		isSearchOnly: variation.isSearchOnly,
 	};
 };
 
@@ -2151,6 +2153,27 @@ const buildBlockTypeItem =
 			blockType.name,
 			'inserter'
 		);
+		const blockVariations = getBlockVariations( blockType.name, 'block' );
+		// Combine inserter and block variations. Block-scope variations without
+		// inserter scope are searchable via slash commands but hidden from browse.
+		const inserterVariationNames = new Set(
+			inserterVariations.map( ( variation ) => variation.name )
+		);
+		const allVariations = [
+			...inserterVariations,
+			...blockVariations
+				.filter(
+					( variation ) =>
+						! inserterVariationNames.has( variation.name )
+				)
+				.map( ( variation ) => ( {
+					...variation,
+					isSearchOnly: true,
+					// Block-scope `isDefault` is for the placeholder picker,
+					// not for the inserter, so don't carry it over.
+					isDefault: false,
+				} ) ),
+		];
 		return {
 			...blockItemBase,
 			initialAttributes: {},
@@ -2159,7 +2182,7 @@ const buildBlockTypeItem =
 			keywords: blockType.keywords,
 			parent: blockType.parent,
 			ancestor: blockType.ancestor,
-			variations: inserterVariations,
+			variations: allVariations,
 			example: blockType.example,
 			utility: 1, // Deprecated.
 		};

packages/block-library/src/heading/edit.js

@@ -15,7 +15,6 @@ import {
 	RichText,
 	useBlockProps,
 	store as blockEditorStore,
-	HeadingLevelDropdown,
 	useBlockEditingMode,
 } from '@wordpress/block-editor';
 
@@ -32,8 +31,7 @@ function HeadingEdit( {
 	style,
 	clientId,
 } ) {
-	const { textAlign, content, level, levelOptions, placeholder, anchor } =
-		attributes;
+	const { textAlign, content, level, placeholder, anchor } = attributes;
 	const tagName = 'h' + level;
 	const blockProps = useBlockProps( {
 		className: clsx( {
@@ -94,13 +92,6 @@ function HeadingEdit( {
 		<>
 			{ blockEditingMode === 'default' && (
 				<BlockControls group="block">
-					<HeadingLevelDropdown
-						value={ level }
-						options={ levelOptions }
-						onChange={ ( newLevel ) =>
-							setAttributes( { level: newLevel } )
-						}
-					/>
 					<AlignmentControl
 						value={ textAlign }
 						onChange={ ( nextAlign ) => {

packages/block-library/src/heading/index.js

@@ -3,7 +3,11 @@
  */
 import { heading as icon } from '@wordpress/icons';
 import { __, sprintf } from '@wordpress/i18n';
-import { privateApis as blocksPrivateApis } from '@wordpress/blocks';
+import {
+	privateApis as blocksPrivateApis,
+	getBlockType,
+	unregisterBlockVariation,
+} from '@wordpress/blocks';
 
 /**
  * Internal dependencies
@@ -86,4 +90,21 @@ if ( window.__experimentalContentOnlyInspectorFields ) {
 	};
 }
 
-export const init = () => initBlock( { name, metadata, settings } );
+export const init = () => {
+	const block = initBlock( { name, metadata, settings } );
+
+	// Unregister heading level variations based on `levelOptions` attribute.
+	// This is for backwards compatibility, as extenders can now unregister the
+	// variation directly: `wp.blocks.unregisterBlockVariation( 'core/heading', 'h1' )`.
+	const levelOptions =
+		getBlockType( name )?.attributes?.levelOptions?.default;
+	if ( levelOptions ) {
+		[ 1, 2, 3, 4, 5, 6 ].forEach( ( level ) => {
+			if ( ! levelOptions.includes( level ) ) {
+				unregisterBlockVariation( name, `h${ level }` );
+			}
+		} );
+	}
+
+	return block;
+};

packages/block-library/src/heading/variations.js

@@ -1,22 +1,44 @@
 /**
  * WordPress dependencies
  */
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import { Path, SVG } from '@wordpress/primitives';
-import { heading } from '@wordpress/icons';
+import {
+	headingLevel1,
+	headingLevel2,
+	headingLevel3,
+	headingLevel4,
+	headingLevel5,
+	headingLevel6,
+} from '@wordpress/icons';
+
+const LEVEL_ICONS = [
+	headingLevel1,
+	headingLevel2,
+	headingLevel3,
+	headingLevel4,
+	headingLevel5,
+	headingLevel6,
+];
 
 const variations = [
-	{
-		name: 'heading',
-		title: __( 'Heading' ),
+	...[ 1, 2, 3, 4, 5, 6 ].map( ( level ) => ( {
+		name: `h${ level }`,
+		title: sprintf(
+			/* translators: %d: heading level e.g: "1", "2", "3" */
+			__( 'Heading %d' ),
+			level
+		),
 		description: __(
 			'Introduce new sections and organize content to help visitors (and search engines) understand the structure of your content.'
 		),
-		isDefault: true,
-		scope: [ 'inserter', 'transform' ],
-		attributes: { fitText: undefined },
-		icon: heading,
-	},
+		icon: LEVEL_ICONS[ level - 1 ],
+		attributes: { level },
+		scope: [ 'block', 'transform' ],
+		keywords: [ `h${ level }` ],
+		isActive: ( blockAttributes ) =>
+			! blockAttributes.fitText && blockAttributes.level === level,
+	} ) ),
 	// There is a hardcoded workaround in packages/block-editor/src/store/selectors.js
 	// to make Stretchy variations appear as the last of their sections in the inserter.
 	{

test/e2e/specs/editor/blocks/heading.spec.js

@@ -365,8 +365,8 @@ test.describe( 'Heading', () => {
 
 		await expect(
 			headingListViewItem,
-			'should show default block name if the content is empty'
-		).toHaveText( 'Heading' );
+			'should show variation name if the content is empty'
+		).toHaveText( 'Heading 2' );
 
 		await editor.canvas
 			.getByRole( 'document', {

test/e2e/specs/editor/plugins/block-variations.spec.js

@@ -112,7 +112,9 @@ test.describe( 'Block variations', () => {
 			.locator( 'role=button[name="Add default block"i]' )
 			.click();
 		await page.keyboard.type( '/Columns' );
-		await page.getByRole( 'option', { name: 'Columns' } ).click();
+		await page
+			.getByRole( 'option', { name: 'Columns', exact: true } )
+			.click();
 
 		await editor.canvas
 			.getByRole( 'list', { name: 'Block variations' } )

test/e2e/specs/editor/various/autocomplete-and-mentions.spec.js

@@ -566,13 +566,11 @@ test.describe( 'Autocomplete (@firefox, @webkit)', () => {
 
 		await page.keyboard.type( 'heading' );
 		await expect(
-			page.locator( `role=option[name="Heading"i]` )
+			page.getByRole( 'option', { name: 'Heading', exact: true } )
 		).toBeVisible();
 		// Get the assertive live region screen reader announcement.
 		await expect(
-			page.getByText(
-				'3 results found, use up and down arrow keys to navigate.'
-			)
+			page.getByText( 'use up and down arrow keys to navigate.' )
 		).toBeVisible();
 	} );
 } );