Ignore alt check for aria-hidden images (#1851)

* Ignore alt check for aria-hidden images

Treat <img> elements with aria-hidden="true" as exempt from the alt attribute requirement. Update rule implementation (src + built dist) to detect aria-hidden (case-insensitive) and skip the warning, add unit tests for aria-hidden="true" and "TRUE", and update the rule documentation with the new behavior and example.

* Handle trimmed aria-hidden for <img> alt rule

Refine alt-require rule to trim and normalize the aria-hidden attribute when deciding whether an <img> needs an alt. The check now inlines mapAttrs['aria-hidden']?.trim().toLowerCase() !== 'true' (removing the previous isAriaHidden variable) so values with surrounding whitespace are treated correctly. Changes applied to both src (TS) and compiled dist (JS) files.

* Test aria-hidden behavior in alt rule

Add tests to alt-require.spec.js to verify aria-hidden handling: an <img> with aria-hidden=" true " (with surrounding spaces) should not trigger an alt error, while an <img> with aria-hidden="false" should produce a warning (checks include rule id, line, column and type).

Author: coliff

dist/core/rules/alt-require.js

@@ -11,7 +11,11 @@ export default {
       const col = event.col + tagName.length + 1
       let selector
 
-      if (tagName === 'img' && !('alt' in mapAttrs)) {
+      if (
+        tagName === 'img' &&
+        !('alt' in mapAttrs) &&
+        mapAttrs['aria-hidden']?.trim().toLowerCase() !== 'true'
+      ) {
         reporter.warn(
           'An alt attribute must be present on <img> elements.',
           event.line,

src/core/rules/alt-require.ts

@@ -18,6 +18,34 @@ describe(`Rules: ${ruleId}`, () => {
     expect(messages.length).toBe(0)
   })
 
+  it('Img tag with aria-hidden="true" and no alt attribute should not result in an error', () => {
+    const code = '<img width="200" height="300" aria-hidden="true">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Img tag with aria-hidden="TRUE" and no alt attribute should not result in an error', () => {
+    const code = '<img width="200" height="300" aria-hidden="TRUE">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Img tag with aria-hidden=" true " and no alt attribute should not result in an error', () => {
+    const code = '<img width="200" height="300" aria-hidden=" true ">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Img tag with aria-hidden="false" and no alt attribute should result in an error', () => {
+    const code = '<img width="200" height="300" aria-hidden="false">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(1)
+    expect(messages[0].rule.id).toBe(ruleId)
+    expect(messages[0].line).toBe(1)
+    expect(messages[0].col).toBe(5)
+    expect(messages[0].type).toBe('warning')
+  })
+
   it('Img tag have not alt attribute should result in an error', () => {
     const code = '<img width="200" height="300">'
     const messages = HTMLHint.verify(code, ruleOptions)

test/rules/alt-require.spec.js

@@ -10,7 +10,7 @@ keywords:
 
 import { Badge } from '@astrojs/starlight/components';
 
-Alt of `img` must be present and alt of `area[href]` and `input[type=image]` must be set with a value.
+Alt of `img` must be present unless the image is hidden from assistive technologies with `aria-hidden="true"`. Alt of `area[href]` and `input[type=image]` must be set with a value.
 
 Level: <Badge text="Warning" variant="caution" />
 
@@ -23,6 +23,7 @@ Level: <Badge text="Warning" variant="caution" />
 
 ```html
 <img src="test.png" alt="test" />
+<img src="decorative.png" aria-hidden="true" />
 <input type="image" alt="test" />
 <area shape="circle" coords="180,139,14" href="test.html" alt="test" />
 ```