Merge pull request #1698 from equalizedigital/steve/pro-808-improper-use-of-link-rule-and-anchors-without-href

Add: support for named anchors as jump targets in link validation

Author: SteveJonesDev

src/pageScanner/checks/link-has-valid-href-or-role.js

@@ -30,6 +30,25 @@ export default {
 			return true;
 		}
 
+		// Allow named anchors used as jump targets: no href, has id/name, no visible content,
+		// and not keyboard-focusable.
+		// Per the HTML spec, <a> without href has role="generic" and is not keyboard focusable,
+		// so it does not create a false link for AT or keyboard users.
+		// Use hasAttribute instead of !href to exclude href="" which is keyboard focusable.
+		// Check children.length to exclude anchors wrapping images or other elements.
+		const id = node.getAttribute( 'id' ) || '';
+		const name = node.getAttribute( 'name' ) || '';
+		const hasAnchorTargetName = id.trim() !== '' || name.trim() !== '';
+
+		const tabindex = node.getAttribute( 'tabindex' );
+		const parsedTabindex = null === tabindex ? null : Number.parseInt( tabindex, 10 );
+		const isKeyboardFocusable =
+			null !== tabindex && ( Number.isNaN( parsedTabindex ) || parsedTabindex >= 0 );
+
+		if ( ! node.hasAttribute( 'href' ) && hasAnchorTargetName && ! isKeyboardFocusable && node.children.length === 0 && node.textContent.trim() === '' ) {
+			return true;
+		}
+
 		const trimmedHref = href ? href.trim() : '';
 
 		// Fail if href is missing, just '#', or contains invalid protocols

tests/jest/rules/linkImproper.test.js

@@ -140,6 +140,53 @@ describe( 'Link Improper Rule', () => {
 			html: '<a href="#" role="menuitem">Menu without aria-expanded</a>',
 			shouldPass: false,
 		},
+
+		// Named anchor (jump target) cases
+		{
+			name: 'Passes when empty anchor is used as a named jump target',
+			html: '<a id="meet-the-team"></a>',
+			shouldPass: true,
+		},
+		{
+			name: 'Passes when whitespace-only anchor is used as a named jump target',
+			html: '<a id="section-top">   </a>',
+			shouldPass: true,
+		},
+		{
+			name: 'Passes when legacy name-only anchor is used as a jump target',
+			html: '<a name="section-top"></a>',
+			shouldPass: true,
+		},
+		{
+			name: 'Fails when legacy name-only anchor has text',
+			html: '<a name="section-top">Text</a>',
+			shouldPass: false,
+		},
+		{
+			name: 'Fails when anchor has id and text content but no href',
+			html: '<a id="meet-the-team">Meet the Team</a>',
+			shouldPass: false,
+		},
+		{
+			name: 'Fails when anchor has id and empty href',
+			html: '<a id="top" href=""></a>',
+			shouldPass: false,
+		},
+		{
+			name: 'Fails when anchor has id and child image but no href',
+			html: '<a id="logo"><img src="logo.png" alt="Home"/></a>',
+			shouldPass: false,
+		},
+		{
+			name: 'Fails when anchor is keyboard focusable via tabindex and has no href',
+			html: '<a id="meet-the-team" tabindex="0"></a>',
+			shouldPass: false,
+		},
+		{
+			name: 'Passes when anchor has tabindex of -1 and no href',
+			html: '<a id="meet-the-team" tabindex="-1"></a>',
+			shouldPass: true,
+		},
 	] )( '$name', async ( { html, shouldPass, setup } ) => {
 		document.body.innerHTML = html;