Navigation Link: Clarify Link To invalid and draft state messages (WordPress#74054)

jeryj · web-flow · commit a579646cdd9a · 2026-02-05T08:39:49.000-06:00
diff --git a/packages/block-library/src/navigation-link/edit.js b/packages/block-library/src/navigation-link/edit.js
@@ -37,7 +37,7 @@ import {
 	Controls,
 	LinkUI,
 	useEntityBinding,
-	MissingEntityHelpText,
+	getInvalidLinkHelpText,
 	useHandleLinkChange,
 	useIsInvalidLink,
 	InvalidDraftDisplay,
@@ -366,6 +366,7 @@ export default function NavigationLinkEdit( {
 	} );
 
 	const missingText = getMissingText( type );
+	const invalidLinkHelpText = getInvalidLinkHelpText();
 
 	return (
 		<>
@@ -400,7 +401,7 @@ export default function NavigationLinkEdit( {
 			<div { ...blockProps }>
 				{ hasMissingEntity && (
 					<VisuallyHidden id={ missingEntityDescriptionId }>
-						<MissingEntityHelpText type={ type } kind={ kind } />
+						{ invalidLinkHelpText }
 					</VisuallyHidden>
 				) }
 				{ /* eslint-disable jsx-a11y/anchor-is-valid */ }
diff --git a/packages/block-library/src/navigation-link/shared/controls.js b/packages/block-library/src/navigation-link/shared/controls.js
@@ -22,6 +22,7 @@ import { useHandleLinkChange } from './use-handle-link-change';
 import { useEntityBinding } from './use-entity-binding';
 import { getSuggestionsQuery } from '../link-ui';
 import { useLinkPreview } from './use-link-preview';
+import { useIsInvalidLink } from './use-is-invalid-link';
 import { unlock } from '../../lock-unlock';
 
 const { LinkPicker } = unlock( blockEditorPrivateApis );
@@ -79,17 +80,26 @@ export function Controls( { attributes, setAttributes, clientId } ) {
 			attributes,
 		} );
 
-	const needsHelpText = hasUrlBinding;
-	const helpText = isBoundEntityAvailable
-		? BindingHelpText( {
-				type: attributes.type,
-				kind: attributes.kind,
-		  } )
-		: MissingEntityHelpText( {
-				type: attributes.type,
-				kind: attributes.kind,
-		  } );
+	const [ isInvalid, isDraft ] = useIsInvalidLink(
+		attributes.kind,
+		attributes.type,
+		entityRecord?.id,
+		hasUrlBinding
+	);
+
+	let helpText = '';
 
+	if ( isInvalid || ( hasUrlBinding && ! isBoundEntityAvailable ) ) {
+		// Show invalid link help text for:
+		// 1. Invalid post-type links (trashed/deleted posts/pages) - via useIsInvalidLink
+		// 2. Missing bound taxonomy entities (deleted categories/tags) - useIsInvalidLink only checks post-types
+		helpText = getInvalidLinkHelpText();
+	} else if ( isDraft ) {
+		helpText = getDraftHelpText( {
+			type: attributes.type,
+			kind: attributes.kind,
+		} );
+	}
 	// Get the link change handler with built-in binding management
 	const handleLinkChange = useHandleLinkChange( {
 		clientId,
@@ -184,7 +194,7 @@ export function Controls( { attributes, setAttributes, clientId } ) {
 						attributes.kind
 					) }
 					label={ __( 'Link to' ) }
-					help={ needsHelpText ? helpText : undefined }
+					help={ helpText ? helpText : undefined }
 				/>
 			</ToolsPanelItem>
 
@@ -243,37 +253,32 @@ export function Controls( { attributes, setAttributes, clientId } ) {
 		</ToolsPanel>
 	);
 }
-
 /**
- * Component to display help text for bound URL attributes.
+ * Returns help text for invalid links.
  *
- * @param {Object} props      - Component props
- * @param {string} props.type - The entity type
- * @param {string} props.kind - The entity kind
- * @return {string} Help text for the bound URL
+ * @return {string} Error help text string (empty string if valid).
  */
-export function BindingHelpText( { type, kind } ) {
-	const entityType = getEntityTypeName( type, kind );
-	return sprintf(
-		/* translators: %s is the entity type (e.g., "page", "post", "category") */
-		__( 'Synced with the selected %s.' ),
-		entityType
+export function getInvalidLinkHelpText() {
+	return __(
+		'This link is invalid and will not appear on your site. Please update the link.'
 	);
 }
 
 /**
- * Component to display error help text for missing entity bindings.
+ * Returns the help text for links to draft entities
  *
- * @param {Object} props      - Component props
+ * @param {Object} props      - Function props
  * @param {string} props.type - The entity type
  * @param {string} props.kind - The entity kind
- * @return {JSX.Element} Error help text component
+ * @return {string} Draft help text
  */
-export function MissingEntityHelpText( { type, kind } ) {
+function getDraftHelpText( { 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.' ),
+		/* translators: %1$s is the entity type (e.g., "page", "post", "category") */
+		__(
+			'This link is to a draft %1$s and will not appear on your site until the %1$s is published.'
+		),
 		entityType
 	);
 }
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, BindingHelpText, MissingEntityHelpText } from './controls';
+export { Controls, getInvalidLinkHelpText } from './controls';
 export { updateAttributes } from './update-attributes';
 export {
 	useEntityBinding,
diff --git a/packages/block-library/src/navigation-link/shared/test/controls.js b/packages/block-library/src/navigation-link/shared/test/controls.js
@@ -32,6 +32,11 @@ jest.mock( '../use-entity-binding', () => ( {
 	} ) ),
 } ) );
 
+// Mock the useIsInvalidLink hook
+jest.mock( '../use-is-invalid-link', () => ( {
+	useIsInvalidLink: jest.fn( () => [ false, false ] ),
+} ) );
+
 describe( 'Controls', () => {
 	// Initialize the mock function
 	beforeAll( () => {
@@ -54,6 +59,18 @@ describe( 'Controls', () => {
 	beforeEach( () => {
 		jest.clearAllMocks();
 		mockUpdateAttributes.mockClear();
+
+		// Reset useEntityBinding mock to default
+		const { useEntityBinding } = require( '../use-entity-binding' );
+		useEntityBinding.mockReturnValue( {
+			hasUrlBinding: false,
+			isBoundEntityAvailable: false,
+			clearBinding: jest.fn(),
+		} );
+
+		// Reset useIsInvalidLink mock to default
+		const { useIsInvalidLink } = require( '../use-is-invalid-link' );
+		useIsInvalidLink.mockReturnValue( [ false, false ] );
 	} );
 
 	it( 'renders all form controls', () => {
@@ -119,77 +136,59 @@ describe( 'Controls', () => {
 	} );
 
 	describe( 'URL binding help text', () => {
-		it( 'shows help text when URL is bound to an entity', () => {
+		it( 'shows invalid link help text when bound entity is not available', () => {
 			const { useEntityBinding } = require( '../use-entity-binding' );
 			useEntityBinding.mockReturnValue( {
 				hasUrlBinding: true,
-				isBoundEntityAvailable: true,
+				isBoundEntityAvailable: false,
 				clearBinding: jest.fn(),
 			} );
 
-			const propsWithBinding = {
+			const propsWithCategoryBinding = {
 				...defaultProps,
 				attributes: {
 					...defaultProps.attributes,
-					type: 'page',
-					kind: 'post-type',
+					type: 'category',
+					kind: 'taxonomy',
 				},
 			};
 
-			render( <Controls { ...propsWithBinding } /> );
+			render( <Controls { ...propsWithCategoryBinding } /> );
 
 			expect(
-				screen.getByText( 'Synced with the selected page.' )
+				screen.getByText(
+					'This link is invalid and will not appear on your site. Please update the link.'
+				)
 			).toBeInTheDocument();
 		} );
 
-		it( 'shows help text for different entity types', () => {
-			const { useEntityBinding } = require( '../use-entity-binding' );
-			useEntityBinding.mockReturnValue( {
-				hasUrlBinding: true,
-				isBoundEntityAvailable: true,
-				clearBinding: jest.fn(),
-			} );
+		it( 'shows draft help text for draft entities', () => {
+			const { useIsInvalidLink } = require( '../use-is-invalid-link' );
+			useIsInvalidLink.mockReturnValue( [ false, true ] ); // isInvalid: false, isDraft: true
 
-			const propsWithCategoryBinding = {
+			const propsWithDraftPage = {
 				...defaultProps,
 				attributes: {
 					...defaultProps.attributes,
-					type: 'category',
-					kind: 'taxonomy',
+					type: 'page',
+					kind: 'post-type',
 				},
 			};
 
-			render( <Controls { ...propsWithCategoryBinding } /> );
+			render( <Controls { ...propsWithDraftPage } /> );
 
 			expect(
-				screen.getByText( 'Synced with the selected category.' )
+				screen.getByText(
+					'This link is to a draft page and will not appear on your site until the page is published.'
+				)
 			).toBeInTheDocument();
 		} );
 
-		it( 'does not show help text when URL is not bound', () => {
-			const { useEntityBinding } = require( '../use-entity-binding' );
-			useEntityBinding.mockReturnValue( {
-				hasUrlBinding: false,
-				clearBinding: jest.fn(),
-			} );
-
-			render( <Controls { ...defaultProps } /> );
-
-			expect(
-				screen.queryByText( /Synced with the selected/ )
-			).not.toBeInTheDocument();
-		} );
-
-		it( 'shows help text for post entity type', () => {
-			const { useEntityBinding } = require( '../use-entity-binding' );
-			useEntityBinding.mockReturnValue( {
-				hasUrlBinding: true,
-				isBoundEntityAvailable: true,
-				clearBinding: jest.fn(),
-			} );
+		it( 'shows draft help text for different entity types', () => {
+			const { useIsInvalidLink } = require( '../use-is-invalid-link' );
+			useIsInvalidLink.mockReturnValue( [ false, true ] );
 
-			const propsWithPostBinding = {
+			const propsWithDraftPost = {
 				...defaultProps,
 				attributes: {
 					...defaultProps.attributes,
@@ -198,35 +197,30 @@ describe( 'Controls', () => {
 				},
 			};
 
-			render( <Controls { ...propsWithPostBinding } /> );
+			render( <Controls { ...propsWithDraftPost } /> );
 
 			expect(
-				screen.getByText( 'Synced with the selected post.' )
+				screen.getByText(
+					'This link is to a draft post and will not appear on your site until the post is published.'
+				)
 			).toBeInTheDocument();
 		} );
 
-		it( 'shows help text for tag entity type', () => {
-			const { useEntityBinding } = require( '../use-entity-binding' );
-			useEntityBinding.mockReturnValue( {
-				hasUrlBinding: true,
-				isBoundEntityAvailable: true,
-				clearBinding: jest.fn(),
-			} );
-
-			const propsWithTagBinding = {
+		it( 'does not show help text for valid link', () => {
+			const propsWithValidLink = {
 				...defaultProps,
 				attributes: {
 					...defaultProps.attributes,
-					type: 'tag',
-					kind: 'taxonomy',
+					url: 'https://example.com',
+					type: 'page',
+					kind: 'post-type',
 				},
 			};
 
-			render( <Controls { ...propsWithTagBinding } /> );
+			render( <Controls { ...propsWithValidLink } /> );
 
-			expect(
-				screen.getByText( 'Synced with the selected tag.' )
-			).toBeInTheDocument();
+			// When link is valid (not invalid, not draft, no binding issues), no help text should be shown
+			expect( screen.queryByText( /This link/ ) ).not.toBeInTheDocument();
 		} );
 	} );
 } );
diff --git a/packages/block-library/src/navigation-link/shared/use-link-preview.js b/packages/block-library/src/navigation-link/shared/use-link-preview.js
@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import { __ } from '@wordpress/i18n';
+import { __, sprintf } from '@wordpress/i18n';
 import { safeDecodeURI } from '@wordpress/url';
 import { privateApis as blockEditorPrivateApis } from '@wordpress/block-editor';
 
@@ -93,10 +93,17 @@ function computeBadges( {
 	}
 
 	// Status badge
-	if ( ! url ) {
+	if ( hasBinding && ! isEntityAvailable ) {
+		badges.push( {
+			label: sprintf(
+				/* translators: %s is the entity type (e.g., "page", "post", "category") */
+				__( 'Missing %s' ),
+				type
+			),
+			intent: 'error',
+		} );
+	} else if ( ! url ) {
 		badges.push( { label: __( 'No link selected' ), intent: 'error' } );
-	} else if ( hasBinding && ! isEntityAvailable ) {
-		badges.push( { label: __( 'Deleted' ), intent: 'error' } );
 	} else if ( entityStatus ) {
 		const statusMap = {
 			publish: { label: __( 'Published' ), intent: 'success' },
diff --git a/test/e2e/specs/editor/blocks/navigation.spec.js b/test/e2e/specs/editor/blocks/navigation.spec.js
@@ -1202,13 +1202,6 @@ test.describe( 'Navigation block', () => {
 				await expect( linkButton ).toContainText(
 					url.pathname.replace( /\/$/, '' )
 				);
-
-				// Verify help text
-				await expect(
-					settingsControls.getByText(
-						'Synced with the selected page.'
-					)
-				).toBeVisible();
 			} );
 
 			await test.step( 'Verify bound link works correctly on frontend', async () => {
@@ -1633,14 +1626,14 @@ test.describe( 'Navigation block', () => {
 
 				// With LinkControlInspector, unavailable entities show a button with error badge
 				const linkButton = settingsControls.getByRole( 'button', {
-					name: /No link selected/i,
+					name: /Missing page/i,
 				} );
 
 				// Button is enabled (can click to fix the link)
 				await expect( linkButton ).toBeEnabled();
 
-				// Button should show "No link selected" for unavailable entity
-				await expect( linkButton ).toContainText( 'No link selected' );
+				// Button should show "Missing page" for unavailable entity
+				await expect( linkButton ).toContainText( 'Missing page' );
 			} );
 
 			await test.step( 'Verify clicking button with error opens link control for fixing', async () => {
@@ -1649,7 +1642,7 @@ test.describe( 'Navigation block', () => {
 					.getByRole( 'tabpanel', { name: 'Settings' } );
 
 				const linkButton = settingsControls.getByRole( 'button', {
-					name: /No link selected/i,
+					name: /Missing page/i,
 				} );
 
 				// Click the button to open the link control and fix the link
