From 51a9483a1d566b750b013013bc774d06ed8dfb96 Mon Sep 17 00:00:00 2001
From: Andrea Fercia <a.fercia@gmail.com>
Date: Thu, 16 Jan 2025 09:46:14 +0100
Subject: [PATCH 1/2] Move html element help messages to the block library
 utils.

---
 .../edit/comments-inspector-controls.js       | 13 +++-----
 .../src/cover/edit/inspector-controls.js      | 22 +------------
 packages/block-library/src/group/edit.js      | 21 +------------
 .../src/query/edit/query-content.js           | 12 +------
 packages/block-library/src/separator/edit.js  |  7 +----
 .../template-part/edit/advanced-controls.js   | 22 +------------
 packages/block-library/src/utils/messages.js  | 31 +++++++++++++++++++
 7 files changed, 41 insertions(+), 87 deletions(-)
 create mode 100644 packages/block-library/src/utils/messages.js

diff --git a/packages/block-library/src/comments/edit/comments-inspector-controls.js b/packages/block-library/src/comments/edit/comments-inspector-controls.js
index 1a33cb68ea38a..fda1fb3cc2e4b 100644
--- a/packages/block-library/src/comments/edit/comments-inspector-controls.js
+++ b/packages/block-library/src/comments/edit/comments-inspector-controls.js
@@ -5,18 +5,15 @@ import { SelectControl } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 import { InspectorControls } from '@wordpress/block-editor';
 
+/**
+ * Internal dependencies
+ */
+import { htmlElementMessages } from '../../utils/messages';
+
 export default function CommentsInspectorControls( {
 	attributes: { tagName },
 	setAttributes,
 } ) {
-	const htmlElementMessages = {
-		section: __(
-			"The <section> element should represent a standalone portion of the document that can't be better represented by another element."
-		),
-		aside: __(
-			"The <aside> element should represent a portion of a document whose content is only indirectly related to the document's main content."
-		),
-	};
 	return (
 		<InspectorControls>
 			<InspectorControls group="advanced">
diff --git a/packages/block-library/src/cover/edit/inspector-controls.js b/packages/block-library/src/cover/edit/inspector-controls.js
index b0d4b435163b7..bca844a9b4ced 100644
--- a/packages/block-library/src/cover/edit/inspector-controls.js
+++ b/packages/block-library/src/cover/edit/inspector-controls.js
@@ -36,6 +36,7 @@ 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 );
 
@@ -183,27 +184,6 @@ export default function CoverInspectorControls( {
 
 	const colorGradientSettings = useMultipleOriginColorsAndGradients();
 
-	const htmlElementMessages = {
-		header: __(
-			'The <header> element should represent introductory content, typically a group of introductory or navigational aids.'
-		),
-		main: __(
-			'The <main> element should be used for the primary content of your document only.'
-		),
-		section: __(
-			"The <section> element should represent a standalone portion of the document that can't be better represented by another element."
-		),
-		article: __(
-			'The <article> element should represent a self-contained, syndicatable portion of the document.'
-		),
-		aside: __(
-			"The <aside> element should represent a portion of a document whose content is only indirectly related to the document's main content."
-		),
-		footer: __(
-			'The <footer> element should represent a footer for its nearest sectioning element (e.g.: <section>, <article>, <main> etc.).'
-		),
-	};
-
 	const dropdownMenuProps = useToolsPanelDropdownMenuProps();
 
 	return (
diff --git a/packages/block-library/src/group/edit.js b/packages/block-library/src/group/edit.js
index 352a6fbc77819..c5588f3b73bb1 100644
--- a/packages/block-library/src/group/edit.js
+++ b/packages/block-library/src/group/edit.js
@@ -18,6 +18,7 @@ import { View } from '@wordpress/primitives';
  * Internal dependencies
  */
 import GroupPlaceHolder, { useShouldShowPlaceHolder } from './placeholder';
+import { htmlElementMessages } from '../utils/messages';
 
 /**
  * Render inspector controls for the Group block.
@@ -29,26 +30,6 @@ import GroupPlaceHolder, { useShouldShowPlaceHolder } from './placeholder';
  * @return {JSX.Element}                The control group.
  */
 function GroupEditControls( { tagName, onSelectTagName } ) {
-	const htmlElementMessages = {
-		header: __(
-			'The <header> element should represent introductory content, typically a group of introductory or navigational aids.'
-		),
-		main: __(
-			'The <main> element should be used for the primary content of your document only.'
-		),
-		section: __(
-			"The <section> element should represent a standalone portion of the document that can't be better represented by another element."
-		),
-		article: __(
-			'The <article> element should represent a self-contained, syndicatable portion of the document.'
-		),
-		aside: __(
-			"The <aside> element should represent a portion of a document whose content is only indirectly related to the document's main content."
-		),
-		footer: __(
-			'The <footer> element should represent a footer for its nearest sectioning element (e.g.: <section>, <article>, <main> etc.).'
-		),
-	};
 	return (
 		<InspectorControls group="advanced">
 			<SelectControl
diff --git a/packages/block-library/src/query/edit/query-content.js b/packages/block-library/src/query/edit/query-content.js
index a608f20bbeb00..459ce2af018c2 100644
--- a/packages/block-library/src/query/edit/query-content.js
+++ b/packages/block-library/src/query/edit/query-content.js
@@ -23,6 +23,7 @@ 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 DEFAULTS_POSTS_PER_PAGE = 3;
 
@@ -132,17 +133,6 @@ export default function QueryContent( {
 		setAttributes( {
 			displayLayout: { ...displayLayout, ...newDisplayLayout },
 		} );
-	const htmlElementMessages = {
-		main: __(
-			'The <main> element should be used for the primary content of your document only.'
-		),
-		section: __(
-			"The <section> element should represent a standalone portion of the document that can't be better represented by another element."
-		),
-		aside: __(
-			"The <aside> element should represent a portion of a document whose content is only indirectly related to the document's main content."
-		),
-	};
 
 	return (
 		<>
diff --git a/packages/block-library/src/separator/edit.js b/packages/block-library/src/separator/edit.js
index c4b832c66158d..ca94ef41f1d8a 100644
--- a/packages/block-library/src/separator/edit.js
+++ b/packages/block-library/src/separator/edit.js
@@ -19,12 +19,7 @@ import { __ } from '@wordpress/i18n';
  * Internal dependencies
  */
 import useDeprecatedOpacity from './use-deprecated-opacity';
-
-const htmlElementMessages = {
-	div: __(
-		'The <div> element should only be used if the separator is a design element that should not be announced.'
-	),
-};
+import { htmlElementMessages } from '../utils/messages';
 
 export default function SeparatorEdit( { attributes, setAttributes } ) {
 	const { backgroundColor, opacity, style, tagName } = attributes;
diff --git a/packages/block-library/src/template-part/edit/advanced-controls.js b/packages/block-library/src/template-part/edit/advanced-controls.js
index 04c6d3387346a..f63c01b71be02 100644
--- a/packages/block-library/src/template-part/edit/advanced-controls.js
+++ b/packages/block-library/src/template-part/edit/advanced-controls.js
@@ -10,27 +10,7 @@ import { useSelect } from '@wordpress/data';
  * Internal dependencies
  */
 import { TemplatePartImportControls } from './import-controls';
-
-const htmlElementMessages = {
-	header: __(
-		'The <header> element should represent introductory content, typically a group of introductory or navigational aids.'
-	),
-	main: __(
-		'The <main> element should be used for the primary content of your document only.'
-	),
-	section: __(
-		"The <section> element should represent a standalone portion of the document that can't be better represented by another element."
-	),
-	article: __(
-		'The <article> element should represent a self-contained, syndicatable portion of the document.'
-	),
-	aside: __(
-		"The <aside> element should represent a portion of a document whose content is only indirectly related to the document's main content."
-	),
-	footer: __(
-		'The <footer> element should represent a footer for its nearest sectioning element (e.g.: <section>, <article>, <main> etc.).'
-	),
-};
+import { htmlElementMessages } from '../../utils/messages';
 
 export function TemplatePartAdvancedControls( {
 	tagName,
diff --git a/packages/block-library/src/utils/messages.js b/packages/block-library/src/utils/messages.js
new file mode 100644
index 0000000000000..e8e1495e64555
--- /dev/null
+++ b/packages/block-library/src/utils/messages.js
@@ -0,0 +1,31 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+export const htmlElementMessages = {
+	article: __(
+		'The <article> element should represent a self-contained, syndicatable portion of the document.'
+	),
+	aside: __(
+		"The <aside> element should represent a portion of a document whose content is only indirectly related to the document's main content."
+	),
+	div: __(
+		'The <div> element should only be used if the separator is a design element with no semantic meaning.'
+	),
+	footer: __(
+		'The <footer> element should represent a footer for its nearest sectioning element (e.g.: <section>, <article>, <main> etc.).'
+	),
+	header: __(
+		'The <header> element should represent introductory content, typically a group of introductory or navigational aids.'
+	),
+	main: __(
+		'The <main> element should be used for the primary content of your document only.'
+	),
+	nav: __(
+		'The <nav> element should be used to identify groups of links that are intended to be used for website or page content navigation.'
+	),
+	section: __(
+		"The <section> element should represent a standalone portion of the document that can't be better represented by another element."
+	),
+};

From 8bd7277e9fbaa01f463f53c01c4462fb2206395a Mon Sep 17 00:00:00 2001
From: Andrea Fercia <a.fercia@gmail.com>
Date: Thu, 16 Jan 2025 10:10:56 +0100
Subject: [PATCH 2/2] Make help message for the div element more generic.

---
 packages/block-library/src/utils/messages.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/block-library/src/utils/messages.js b/packages/block-library/src/utils/messages.js
index e8e1495e64555..564bb32ee951e 100644
--- a/packages/block-library/src/utils/messages.js
+++ b/packages/block-library/src/utils/messages.js
@@ -11,7 +11,7 @@ export const htmlElementMessages = {
 		"The <aside> element should represent a portion of a document whose content is only indirectly related to the document's main content."
 	),
 	div: __(
-		'The <div> element should only be used if the separator is a design element with no semantic meaning.'
+		'The <div> element should only be used if the block is a design element with no semantic meaning.'
 	),
 	footer: __(
 		'The <footer> element should represent a footer for its nearest sectioning element (e.g.: <section>, <article>, <main> etc.).'