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.

Author: coliff

dist/core/rules/alt-require.js

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

src/core/rules/alt-require.ts

@@ -18,6 +18,18 @@ 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 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" />
 ```