Fix a11y of descriptions and alerts for "Invalid" Nav Items (#73177)

jeryj · getdave · gutenbergplugin · commit bcc4ea390abd · 2025-11-13T16:29:18.000Z
The role="alert" and aria-live="polite" attributes were causing the error message to be announced twice to screen readers. Since this text is referenced via aria-describedby on the input field, it will be read when users focus the field - no live announcement is needed.

This also adds aria-invalid and aria-describedBy to the navigation link block if the synced entity is not found. This allows screen reader users to be aware of the issue on canvas as well.

---------

Co-authored-by: Dave Smith &lt;getdavemail@gmail.com&gt;
diff --git a/packages/block-library/src/navigation-link/edit.js b/packages/block-library/src/navigation-link/edit.js
@@ -8,9 +8,13 @@ import clsx from 'clsx';
  */
 import { createBlock } from '@wordpress/blocks';
 import { useSelect, useDispatch } from '@wordpress/data';
-import { ToolbarButton, ToolbarGroup } from '@wordpress/components';
+import {
+	ToolbarButton,
+	ToolbarGroup,
+	VisuallyHidden,
+} from '@wordpress/components';
 import { displayShortcut, isKeyboardEvent } from '@wordpress/keycodes';
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import {
 	BlockControls,
 	InspectorControls,
@@ -26,13 +30,19 @@ import { useState, useEffect, useRef, useCallback } from '@wordpress/element';
 import { decodeEntities } from '@wordpress/html-entities';
 import { link as linkIcon, addSubmenu } from '@wordpress/icons';
 import { store as coreStore } from '@wordpress/core-data';
-import { useMergeRefs, usePrevious } from '@wordpress/compose';
+import { useMergeRefs, usePrevious, useInstanceId } from '@wordpress/compose';
 
 /**
  * Internal dependencies
  */
 import { getColors } from '../navigation/edit/utils';
-import { Controls, LinkUI, updateAttributes, useEntityBinding } from './shared';
+import {
+	Controls,
+	LinkUI,
+	updateAttributes,
+	useEntityBinding,
+	MissingEntityHelpText,
+} from './shared';
 
 const DEFAULT_BLOCK = { name: 'core/navigation-link' };
 const NESTING_BLOCK_NAMES = [
@@ -394,6 +404,12 @@ export default function NavigationLinkEdit( {
 		}
 	}
 
+	const instanceId = useInstanceId( NavigationLinkEdit );
+	const hasMissingEntity = hasUrlBinding && ! isBoundEntityAvailable;
+	const missingEntityDescriptionId = hasMissingEntity
+		? sprintf( 'navigation-link-edit-%d-desc', instanceId )
+		: undefined;
+
 	const blockProps = useBlockProps( {
 		ref: useMergeRefs( [ setPopoverAnchor, listItemRef ] ),
 		className: clsx( 'wp-block-navigation-item', {
@@ -407,6 +423,8 @@ export default function NavigationLinkEdit( {
 			[ getColorClassName( 'background-color', backgroundColor ) ]:
 				!! backgroundColor,
 		} ),
+		'aria-describedby': missingEntityDescriptionId,
+		'aria-invalid': hasMissingEntity,
 		style: {
 			color: ! textColor && customTextColor,
 			backgroundColor: ! backgroundColor && customBackgroundColor,
@@ -482,6 +500,11 @@ export default function NavigationLinkEdit( {
 				/>
 			</InspectorControls>
 			<div { ...blockProps }>
+				{ hasMissingEntity && (
+					<VisuallyHidden id={ missingEntityDescriptionId }>
+						<MissingEntityHelpText type={ type } kind={ kind } />
+					</VisuallyHidden>
+				) }
 				{ /* eslint-disable jsx-a11y/anchor-is-valid */ }
 				<a className={ classes }>
 					{ /* eslint-enable */ }
diff --git a/packages/block-library/src/navigation-link/shared/controls.js b/packages/block-library/src/navigation-link/shared/controls.js
@@ -221,7 +221,7 @@ export function Controls( { attributes, setAttributes, clientId } ) {
 					} }
 					help={
 						hasUrlBinding && ! isBoundEntityAvailable ? (
-							<MissingEntityHelpText
+							<MissingEntityHelp
 								id={ helpTextId }
 								type={ attributes.type }
 								kind={ attributes.kind }
@@ -327,7 +327,7 @@ export function Controls( { attributes, setAttributes, clientId } ) {
  * @param {string} props.kind - The entity kind
  * @return {string} Help text for the bound URL
  */
-function BindingHelpText( { type, kind } ) {
+export function BindingHelpText( { type, kind } ) {
 	const entityType = getEntityTypeName( type, kind );
 	return sprintf(
 		/* translators: %s is the entity type (e.g., "page", "post", "category") */
@@ -340,27 +340,23 @@ function BindingHelpText( { type, kind } ) {
  * Component to display error help text for missing entity bindings.
  *
  * @param {Object} props      - Component props
- * @param {string} props.id   - ID for the help text element (for aria-describedby)
  * @param {string} props.type - The entity type
  * @param {string} props.kind - The entity kind
  * @return {JSX.Element} Error help text component
  */
-function MissingEntityHelpText( { id, type, kind } ) {
+export function MissingEntityHelpText( { type, kind } ) {
 	const entityType = getEntityTypeName( type, kind );
+	return sprintf(
+		/* translators: %s is the entity type (e.g., "page", "post", "category") */
+		__( 'Synced %s is missing. Please update or remove this link.' ),
+		entityType
+	);
+}
+
+function MissingEntityHelp( { id, type, kind } ) {
 	return (
-		<span
-			id={ id }
-			className="navigation-link-control__error-text"
-			role="alert"
-			aria-live="polite"
-		>
-			{ sprintf(
-				/* translators: %s is the entity type (e.g., "page", "post", "category") */
-				__(
-					'Synced %s is missing. Please update or remove this link.'
-				),
-				entityType
-			) }
+		<span id={ id } className="navigation-link-control__error-text">
+			<MissingEntityHelpText type={ type } kind={ kind } />
 		</span>
 	);
 }
diff --git a/packages/block-library/src/navigation-link/shared/index.js b/packages/block-library/src/navigation-link/shared/index.js
@@ -5,7 +5,7 @@
  * to reduce code duplication and ensure consistent behavior.
  */
 
-export { Controls } from './controls';
+export { Controls, BindingHelpText, MissingEntityHelpText } from './controls';
 export { updateAttributes } from './update-attributes';
 export {
 	useEntityBinding,
