Block Editor: Add new HTMLElementControl component (#69904)

Sukhendu2002 · Sukhendu2002 · Mamaduka · web-flow · commit 01a1f973d9fa · 2025-04-25T10:58:46.000+04:00
Co-authored-by: Sukhendu2002 &lt;sukhendu2002@git.wordpress.org&gt;
Co-authored-by: Mamaduka &lt;mamaduka@git.wordpress.org&gt;
Co-authored-by: t-hamano &lt;wildworks@git.wordpress.org&gt;
Co-authored-by: skorasaurus &lt;skorasaurus@git.wordpress.org&gt;
Co-authored-by: carolinan &lt;poena@git.wordpress.org&gt;
diff --git a/packages/block-editor/src/components/html-element-control/index.js b/packages/block-editor/src/components/html-element-control/index.js
@@ -0,0 +1,109 @@
+/**
+ * WordPress dependencies
+ */
+import { __, sprintf } from '@wordpress/i18n';
+import {
+	SelectControl,
+	Notice,
+	__experimentalVStack as VStack,
+} from '@wordpress/components';
+import { useSelect } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { store as blockEditorStore } from '../../store';
+import { htmlElementMessages } from './messages';
+
+/**
+ * Renders a SelectControl for choosing HTML elements with validation
+ * to prevent duplicate <main> elements.
+ *
+ * @param {Object}   props          Component props.
+ * @param {string}   props.tagName  The current HTML tag name.
+ * @param {Function} props.onChange Function to call when the tag is changed.
+ * @param {string}   props.clientId The client ID of the current block.
+ * @param {Array}    props.options  SelectControl options (optional).
+ *
+ * @return {Component} The HTML element select control with validation.
+ */
+export default function HTMLElementControl( {
+	tagName,
+	onChange,
+	clientId,
+	options = [
+		{ label: __( 'Default (<div>)' ), value: 'div' },
+		{ label: '<header>', value: 'header' },
+		{ label: '<main>', value: 'main' },
+		{ label: '<section>', value: 'section' },
+		{ label: '<article>', value: 'article' },
+		{ label: '<aside>', value: 'aside' },
+		{ label: '<footer>', value: 'footer' },
+	],
+} ) {
+	const checkForMainTag =
+		!! clientId && options.some( ( option ) => option.value === 'main' );
+
+	const hasMainElementElsewhere = useSelect(
+		( select ) => {
+			if ( ! checkForMainTag ) {
+				return false;
+			}
+
+			const { getClientIdsWithDescendants, getBlockAttributes } =
+				select( blockEditorStore );
+
+			return getClientIdsWithDescendants().some( ( id ) => {
+				// Skip the current block.
+				if ( id === clientId ) {
+					return false;
+				}
+
+				return getBlockAttributes( id )?.tagName === 'main';
+			} );
+		},
+		[ clientId, checkForMainTag ]
+	);
+
+	// Create a modified options array that disables the main option if needed.
+	const modifiedOptions = options.map( ( option ) => {
+		if (
+			option.value === 'main' &&
+			hasMainElementElsewhere &&
+			tagName !== 'main'
+		) {
+			return {
+				...option,
+				disabled: true,
+				label: sprintf(
+					/* translators: %s: HTML element name */
+					__( '%s (Already in use)' ),
+					option.label
+				),
+			};
+		}
+		return option;
+	} );
+
+	return (
+		<VStack spacing={ 2 }>
+			<SelectControl
+				__nextHasNoMarginBottom
+				__next40pxDefaultSize
+				label={ __( 'HTML element' ) }
+				options={ modifiedOptions }
+				value={ tagName }
+				onChange={ onChange }
+				help={ htmlElementMessages[ tagName ] }
+			/>
+
+			{ tagName === 'main' && hasMainElementElsewhere && (
+				<Notice status="warning" isDismissible={ false }>
+					{ __(
+						'Multiple <main> elements detected. This is not valid HTML and may cause accessibility issues. Please change this HTML element.'
+					) }
+				</Notice>
+			) }
+		</VStack>
+	);
+}
diff --git a/packages/block-editor/src/components/html-element-control/messages.js b/packages/block-editor/src/components/html-element-control/messages.js
@@ -3,6 +3,9 @@
  */
 import { __ } from '@wordpress/i18n';
 
+/**
+ * Messages providing helpful descriptions for HTML elements.
+ */
 export const htmlElementMessages = {
 	article: __(
 		'The <article> element should represent a self-contained, syndicatable portion of the document.'
diff --git a/packages/block-editor/src/private-apis.js b/packages/block-editor/src/private-apis.js
@@ -50,6 +50,7 @@ import useBlockDisplayTitle from './components/block-title/use-block-display-tit
 import TabbedSidebar from './components/tabbed-sidebar';
 import CommentIconSlotFill from './components/collab/block-comment-icon-slot';
 import CommentIconToolbarSlotFill from './components/collab/block-comment-icon-toolbar-slot';
+import HTMLElementControl from './components/html-element-control';
 /**
  * Private @wordpress/block-editor APIs.
  */
@@ -80,6 +81,7 @@ lock( privateApis, {
 	TextAlignmentControl,
 	usesContextKey,
 	useFlashEditableBlocks,
+	HTMLElementControl,
 	useZoomOut,
 	globalStylesDataKey,
 	globalStylesLinksDataKey,
diff --git a/packages/block-editor/src/private-apis.native.js b/packages/block-editor/src/private-apis.native.js
@@ -6,6 +6,7 @@ import { ExperimentalBlockEditorProvider } from './components/provider';
 import { getRichTextValues } from './components/rich-text/get-rich-text-values';
 import { lock } from './lock-unlock';
 import { PrivateRichText } from './components/rich-text/';
+import HTMLElementControl from './components/html-element-control';
 
 /**
  * Private @wordpress/block-editor APIs.
@@ -16,4 +17,5 @@ lock( privateApis, {
 	ExperimentalBlockEditorProvider,
 	getRichTextValues,
 	PrivateRichText,
+	HTMLElementControl,
 } );
diff --git a/packages/block-library/src/comments/edit/comments-inspector-controls.js b/packages/block-library/src/comments/edit/comments-inspector-controls.js
@@ -1,36 +1,38 @@
 /**
  * WordPress dependencies
  */
-import { SelectControl } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
-import { InspectorControls } from '@wordpress/block-editor';
+import {
+	InspectorControls,
+	privateApis as blockEditorPrivateApis,
+} from '@wordpress/block-editor';
 
 /**
  * Internal dependencies
  */
-import { htmlElementMessages } from '../../utils/messages';
+import { unlock } from '../../lock-unlock';
+
+const { HTMLElementControl } = unlock( blockEditorPrivateApis );
 
 export default function CommentsInspectorControls( {
 	attributes: { tagName },
 	setAttributes,
+	clientId,
 } ) {
 	return (
 		<InspectorControls>
 			<InspectorControls group="advanced">
-				<SelectControl
-					__nextHasNoMarginBottom
-					__next40pxDefaultSize
-					label={ __( 'HTML element' ) }
+				<HTMLElementControl
+					tagName={ tagName }
+					onChange={ ( value ) =>
+						setAttributes( { tagName: value } )
+					}
+					clientId={ clientId }
 					options={ [
 						{ label: __( 'Default (<div>)' ), value: 'div' },
 						{ label: '<section>', value: 'section' },
 						{ label: '<aside>', value: 'aside' },
 					] }
-					value={ tagName }
-					onChange={ ( value ) =>
-						setAttributes( { tagName: value } )
-					}
-					help={ htmlElementMessages[ tagName ] }
 				/>
 			</InspectorControls>
 		</InspectorControls>
diff --git a/packages/block-library/src/comments/edit/index.js b/packages/block-library/src/comments/edit/index.js
@@ -11,7 +11,7 @@ import CommentsLegacy from './comments-legacy';
 import TEMPLATE from './template';
 
 export default function CommentsEdit( props ) {
-	const { attributes, setAttributes } = props;
+	const { attributes, setAttributes, clientId } = props;
 	const { tagName: TagName, legacy } = attributes;
 
 	const blockProps = useBlockProps();
@@ -28,6 +28,7 @@ export default function CommentsEdit( props ) {
 			<CommentsInspectorControls
 				attributes={ attributes }
 				setAttributes={ setAttributes }
+				clientId={ clientId }
 			/>
 			<TagName { ...innerBlocksProps } />
 		</>
diff --git a/packages/block-library/src/cover/edit/inspector-controls.js b/packages/block-library/src/cover/edit/inspector-controls.js
@@ -8,7 +8,6 @@ import {
 	RangeControl,
 	TextareaControl,
 	ToggleControl,
-	SelectControl,
 	__experimentalUseCustomUnits as useCustomUnits,
 	__experimentalToolsPanel as ToolsPanel,
 	__experimentalToolsPanelItem as ToolsPanelItem,
@@ -36,9 +35,10 @@ import { COVER_MIN_HEIGHT, mediaPosition } from '../shared';
 import { unlock } from '../../lock-unlock';
 import { useToolsPanelDropdownMenuProps } from '../../utils/hooks';
 import { DEFAULT_MEDIA_SIZE_SLUG } from '../constants';
-import { htmlElementMessages } from '../../utils/messages';
 
-const { cleanEmptyObject, ResolutionTool } = unlock( blockEditorPrivateApis );
+const { cleanEmptyObject, ResolutionTool, HTMLElementControl } = unlock(
+	blockEditorPrivateApis
+);
 
 function CoverHeightInput( {
 	onChange,
@@ -421,10 +421,12 @@ export default function CoverInspectorControls( {
 				</ToolsPanelItem>
 			</InspectorControls>
 			<InspectorControls group="advanced">
-				<SelectControl
-					__nextHasNoMarginBottom
-					__next40pxDefaultSize
-					label={ __( 'HTML element' ) }
+				<HTMLElementControl
+					tagName={ tagName }
+					onChange={ ( value ) =>
+						setAttributes( { tagName: value } )
+					}
+					clientId={ clientId }
 					options={ [
 						{ label: __( 'Default (<div>)' ), value: 'div' },
 						{ label: '<header>', value: 'header' },
@@ -434,11 +436,6 @@ export default function CoverInspectorControls( {
 						{ label: '<aside>', value: 'aside' },
 						{ label: '<footer>', value: 'footer' },
 					] }
-					value={ tagName }
-					onChange={ ( value ) =>
-						setAttributes( { tagName: value } )
-					}
-					help={ htmlElementMessages[ tagName ] }
 				/>
 			</InspectorControls>
 		</>
diff --git a/packages/block-library/src/group/edit.js b/packages/block-library/src/group/edit.js
@@ -8,8 +8,8 @@ import {
 	InspectorControls,
 	useInnerBlocksProps,
 	store as blockEditorStore,
+	privateApis as blockEditorPrivateApis,
 } from '@wordpress/block-editor';
-import { SelectControl } from '@wordpress/components';
 import { useRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 import { View } from '@wordpress/primitives';
@@ -18,24 +18,27 @@ import { View } from '@wordpress/primitives';
  * Internal dependencies
  */
 import GroupPlaceHolder, { useShouldShowPlaceHolder } from './placeholder';
-import { htmlElementMessages } from '../utils/messages';
+import { unlock } from '../lock-unlock';
+
+const { HTMLElementControl } = unlock( blockEditorPrivateApis );
 
 /**
  * Render inspector controls for the Group block.
  *
  * @param {Object}   props                 Component props.
  * @param {string}   props.tagName         The HTML tag name.
  * @param {Function} props.onSelectTagName onChange function for the SelectControl.
+ * @param {string}   props.clientId        The client ID of the current block.
  *
  * @return {JSX.Element}                The control group.
  */
-function GroupEditControls( { tagName, onSelectTagName } ) {
+function GroupEditControls( { tagName, onSelectTagName, clientId } ) {
 	return (
 		<InspectorControls group="advanced">
-			<SelectControl
-				__nextHasNoMarginBottom
-				__next40pxDefaultSize
-				label={ __( 'HTML element' ) }
+			<HTMLElementControl
+				tagName={ tagName }
+				onChange={ onSelectTagName }
+				clientId={ clientId }
 				options={ [
 					{ label: __( 'Default (<div>)' ), value: 'div' },
 					{ label: '<header>', value: 'header' },
@@ -45,9 +48,6 @@ function GroupEditControls( { tagName, onSelectTagName } ) {
 					{ label: '<aside>', value: 'aside' },
 					{ label: '<footer>', value: 'footer' },
 				] }
-				value={ tagName }
-				onChange={ onSelectTagName }
-				help={ htmlElementMessages[ tagName ] }
 			/>
 		</InspectorControls>
 	);
@@ -129,6 +129,7 @@ function GroupEdit( { attributes, name, setAttributes, clientId } ) {
 				onSelectTagName={ ( value ) =>
 					setAttributes( { tagName: value } )
 				}
+				clientId={ clientId }
 			/>
 			{ showPlaceholder && (
 				<View>
diff --git a/packages/block-library/src/query/edit/query-content.js b/packages/block-library/src/query/edit/query-content.js
@@ -10,20 +10,22 @@ import {
 	useBlockProps,
 	store as blockEditorStore,
 	useInnerBlocksProps,
+	privateApis as blockEditorPrivateApis,
 } from '@wordpress/block-editor';
-import { SelectControl } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 import { store as coreStore } from '@wordpress/core-data';
 
 /**
  * Internal dependencies
  */
 import EnhancedPaginationControl from './inspector-controls/enhanced-pagination-control';
+import { unlock } from '../../lock-unlock';
 import QueryInspectorControls from './inspector-controls';
 import EnhancedPaginationModal from './enhanced-pagination-modal';
 import { getQueryContextFromTemplate } from '../utils';
 import QueryToolbar from './query-toolbar';
-import { htmlElementMessages } from '../../utils/messages';
+
+const { HTMLElementControl } = unlock( blockEditorPrivateApis );
 
 const DEFAULTS_POSTS_PER_PAGE = 3;
 
@@ -147,21 +149,18 @@ export default function QueryContent( {
 				<QueryToolbar attributes={ attributes } clientId={ clientId } />
 			</BlockControls>
 			<InspectorControls group="advanced">
-				<SelectControl
-					__nextHasNoMarginBottom
-					__next40pxDefaultSize
-					label={ __( 'HTML element' ) }
+				<HTMLElementControl
+					tagName={ TagName }
+					onChange={ ( value ) =>
+						setAttributes( { tagName: value } )
+					}
+					clientId={ clientId }
 					options={ [
 						{ label: __( 'Default (<div>)' ), value: 'div' },
 						{ label: '<main>', value: 'main' },
 						{ label: '<section>', value: 'section' },
 						{ label: '<aside>', value: 'aside' },
 					] }
-					value={ TagName }
-					onChange={ ( value ) =>
-						setAttributes( { tagName: value } )
-					}
-					help={ htmlElementMessages[ TagName ] }
 				/>
 				<EnhancedPaginationControl
 					enhancedPagination={ enhancedPagination }
diff --git a/packages/block-library/src/separator/edit.js b/packages/block-library/src/separator/edit.js
diff --git a/packages/block-library/src/template-part/edit/advanced-controls.js b/packages/block-library/src/template-part/edit/advanced-controls.js
diff --git a/packages/block-library/src/template-part/edit/index.js b/packages/block-library/src/template-part/edit/index.js
