Add new rule: frame-title-require (#1629)

Author: coliff

.cspell.json

@@ -32,6 +32,7 @@
     "idclassaddisabled",
     "Infima",
     "invision",
+    "Labelledby",
     "langtag",
     "mingo",
     "msapplication",

dist/core/rules/index.js

@@ -0,0 +1,39 @@
+import { Rule } from '../types'
+
+export default {
+  id: 'frame-title-require',
+  description: 'A <frame> or <iframe> element must have an accessible name.',
+  init(parser, reporter) {
+    parser.addListener('tagstart', (event) => {
+      const tagName = event.tagName.toLowerCase()
+      const mapAttrs = parser.getMapAttrs(event.attrs)
+      const col = event.col + tagName.length + 1
+
+      if (tagName === 'frame' || tagName === 'iframe') {
+        // Check if element has role="presentation" or role="none"
+        const role = mapAttrs['role']
+        if (role === 'presentation' || role === 'none') {
+          return // Rule passes - element semantics are overridden
+        }
+
+        // Check for accessible name attributes
+        const hasAriaLabel =
+          'aria-label' in mapAttrs && mapAttrs['aria-label'].trim() !== ''
+        const hasAriaLabelledby =
+          'aria-labelledby' in mapAttrs &&
+          mapAttrs['aria-labelledby'].trim() !== ''
+        const hasTitle = 'title' in mapAttrs && mapAttrs['title'].trim() !== ''
+
+        if (!hasAriaLabel && !hasAriaLabelledby && !hasTitle) {
+          reporter.warn(
+            `A <${tagName}> element must have an accessible name.`,
+            event.line,
+            col,
+            this,
+            event.raw
+          )
+        }
+      }
+    })
+  },
+} as Rule

src/core/rules/frame-title-require.ts

@@ -12,6 +12,7 @@ export { default as buttonTypeRequire } from './button-type-require'
 export { default as doctypeFirst } from './doctype-first'
 export { default as doctypeHTML5 } from './doctype-html5'
 export { default as emptyTagNotSelfClosed } from './empty-tag-not-self-closed'
+export { default as frameTitleRequire } from './frame-title-require'
 export { default as h1Require } from './h1-require'
 export { default as headScriptDisabled } from './head-script-disabled'
 export { default as hrefAbsOrRel } from './href-abs-or-rel'

src/core/rules/index.ts

@@ -0,0 +1,139 @@
+const HTMLHint = require('../../dist/htmlhint.js').HTMLHint
+
+const ruleId = 'frame-title-require'
+const ruleOptions = {}
+
+ruleOptions[ruleId] = true
+
+describe(`Rules: ${ruleId}`, () => {
+  it('Frame with aria-label should not result in an error', () => {
+    const code = '<frame src="test.html" aria-label="Test frame">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Iframe with aria-label should not result in an error', () => {
+    const code = '<iframe src="test.html" aria-label="Test iframe"></iframe>'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Frame with aria-labelledby should not result in an error', () => {
+    const code = '<frame src="test.html" aria-labelledby="label1">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Iframe with aria-labelledby should not result in an error', () => {
+    const code = '<iframe src="test.html" aria-labelledby="label1"></iframe>'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Frame with title should not result in an error', () => {
+    const code = '<frame src="test.html" title="Test frame">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Iframe with title should not result in an error', () => {
+    const code = '<iframe src="test.html" title="Test iframe"></iframe>'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Frame with role="presentation" should not result in an error', () => {
+    const code = '<frame src="test.html" role="presentation">'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Iframe with role="none" should not result in an error', () => {
+    const code = '<iframe src="test.html" role="none"></iframe>'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+
+  it('Frame without accessible name should result in an error', () => {
+    const code = '<frame src="test.html">'
+    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(7)
+    expect(messages[0].type).toBe('warning')
+    expect(messages[0].message).toBe(
+      'A <frame> element must have an accessible name.'
+    )
+  })
+
+  it('Iframe without accessible name should result in an error', () => {
+    const code = '<iframe src="test.html"></iframe>'
+    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(8)
+    expect(messages[0].type).toBe('warning')
+    expect(messages[0].message).toBe(
+      'A <iframe> element must have an accessible name.'
+    )
+  })
+
+  it('Frame with empty aria-label should result in an error', () => {
+    const code = '<frame src="test.html" aria-label="">'
+    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(7)
+    expect(messages[0].type).toBe('warning')
+  })
+
+  it('Iframe with empty title should result in an error', () => {
+    const code = '<iframe src="test.html" title=""></iframe>'
+    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(8)
+    expect(messages[0].type).toBe('warning')
+  })
+
+  it('Frame with whitespace-only aria-label should result in an error', () => {
+    const code = '<frame src="test.html" aria-label="   ">'
+    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(7)
+    expect(messages[0].type).toBe('warning')
+  })
+
+  it('Iframe with whitespace-only aria-labelledby should result in an error', () => {
+    const code = '<iframe src="test.html" aria-labelledby="  "></iframe>'
+    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(8)
+    expect(messages[0].type).toBe('warning')
+  })
+
+  it('Multiple iframes - one valid, one invalid should result in one error', () => {
+    const code =
+      '<iframe src="test1.html" title="Valid frame"></iframe><iframe src="test2.html"></iframe>'
+    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(62)
+    expect(messages[0].type).toBe('warning')
+  })
+
+  it('Other elements should not be affected', () => {
+    const code = '<div><p>Content</p></div>'
+    const messages = HTMLHint.verify(code, ruleOptions)
+    expect(messages.length).toBe(0)
+  })
+})

test/rules/frame-title-require.spec.js

@@ -31,6 +31,7 @@ draft: true
 - [`attr-value-single-quotes`](/rules/attr-value-single-quotes): Attribute values must be in single quotes.
 - [`attr-whitespace`](/rules/attr-whitespace): No leading or trailing spaces in attribute values.
 - [`button-type-require`](/rules/button-type-require): The type attribute of a button element must be present with a valid value: "button", "submit", or "reset".
+- [`frame-title-require`](/rules/frame-title-require): A `<frame>` or `<iframe>` element must have an accessible name.
 - [`input-requires-label`](/rules/input-requires-label): All [ input ] tags must have a corresponding [ label ] tag.
 
 ## Tags

website/src/content/docs/list-rules.md

@@ -0,0 +1,38 @@
+---
+id: frame-title-require
+title: frame-title-require
+description: Requires that frame and iframe elements have an accessible name for screen readers and assistive technologies.
+sidebar:
+  hidden: true
+  badge: New
+---
+
+import { Badge } from '@astrojs/starlight/components';
+
+A `<frame>` or `<iframe>` element must have an accessible name.
+
+Level: <Badge text="Warning" variant="caution" />
+
+## Config value
+
+- `true`: enable rule
+- `false`: disable rule
+
+### The following patterns are **not** considered rule violations
+
+```html
+<iframe src="content.html" aria-label="Interactive content"></iframe>
+<iframe src="content.html" aria-labelledby="frame-heading"></iframe>
+<iframe src="content.html" title="Embedded content"></iframe>
+<iframe src="content.html" role="presentation"></iframe>
+<frame src="content.html" title="Navigation frame">
+```
+
+### The following patterns are considered rule violations
+
+```html
+<iframe src="content.html"></iframe>
+<iframe src="content.html" aria-label=""></iframe>
+<iframe src="content.html" title=""></iframe>
+<frame src="content.html">
+```