feat(template-require-iframe-title): split strict whitespace-only check into opt-out option

Two changes, both addressing fallacies flagged in review-pr-bodies.md:

1. Document that SC 4.1.2 (Name, Role, Value) is the normative requirement;
   H64 is a sufficient technique illustrating one way to meet it. Earlier
   framing attributed the requirement to H64 itself — same pattern as
   template-heading-level's miscited G141.

2. Whitespace-only `title="   "` is technically spec-compliant: ACCNAME 1.2
   step 2I (Tooltip) does not whitespace-trim like step 2D (aria-label)
   does. Keeping the strict flag as default (authoring hygiene — 3 spaces
   is useless as an accessible name in practice) but exposing
   `allowWhitespaceOnlyTitle: boolean` (default false) so teams that want
   spec-aligned behavior can opt out. Empty-string `title=""` and invalid
   mustache literals (null/undefined/number/boolean) remain always flagged:
   those are correctness, not style.

Author: johanrd

docs/rules/template-require-iframe-title.md

@@ -6,9 +6,11 @@
 
 ## `<iframe>`
 
-`<iframe>` elements must have a unique title property to indicate its content to the user.
-
-This rule takes no arguments.
+`<iframe>` elements must have a unique title property so assistive
+technology can convey their content to the user. The normative
+requirement is [WCAG SC 4.1.2 (Name, Role, Value)](https://www.w3.org/TR/UNDERSTANDING-WCAG20/ensure-compat-rsv.html);
+the `title` attribute is *one sufficient technique* for meeting it
+(sufficient technique [H64](https://www.w3.org/WAI/WCAG21/Techniques/html/H64)).
 
 ## Examples
 
@@ -27,12 +29,43 @@ This rule **forbids** the following:
 <template>
   <iframe />
   <iframe title='' />
+  <iframe title='   ' />
+  <iframe title={{null}} />
+  <iframe title={{undefined}} />
+  <iframe title={{42}} />
 </template>
 ```
 
+Whitespace-only `title` (`"   "`) is flagged by default as an
+authoring-hygiene check: HTML and ACCNAME technically permit it (step 2I
+doesn't trim), but a whitespace-only accessible name is useless in
+practice. Suppress this specific strictness via `allowWhitespaceOnlyTitle:
+true` if your codebase needs it.
+
+## Configuration
+
+- `allowWhitespaceOnlyTitle` (`boolean`, default `false`): when `true`,
+  `<iframe title="   ">` is accepted. Empty-string `title=""` and
+  non-string mustache literals (`{{null}}`, `{{undefined}}`, `{{42}}`) are
+  still flagged.
+
+```js
+{
+  rules: {
+    'ember/template-require-iframe-title': [
+      'error',
+      { allowWhitespaceOnlyTitle: true },
+    ],
+  },
+}
+```
+
 ## References
 
-- [Deque University](https://dequeuniversity.com/rules/axe/1.1/frame-title)
-- [Technique H65: Using the title attribute of the frame and iframe elements](https://www.w3.org/TR/2014/NOTE-WCAG20-TECHS-20140408/H64)
-- [WCAG Success Criterion 2.4.1 - Bypass Blocks](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-skip.html)
-- [WCAG Success Criterion 4.1.2 - Name, Role, Value](https://www.w3.org/TR/UNDERSTANDING-WCAG20/ensure-compat-rsv.html)
+- [WCAG SC 4.1.2 — Name, Role, Value](https://www.w3.org/TR/UNDERSTANDING-WCAG20/ensure-compat-rsv.html)
+  — the normative requirement.
+- [WCAG Technique H64 — Using the title attribute of the iframe element](https://www.w3.org/WAI/WCAG21/Techniques/html/H64)
+  — a sufficient technique for SC 4.1.2, not itself normative.
+- [WCAG Success Criterion 2.4.1 — Bypass Blocks](https://www.w3.org/TR/UNDERSTANDING-WCAG20/navigation-mechanisms-skip.html)
+- [ACCNAME 1.2 — accessible-name computation](https://www.w3.org/TR/accname-1.2/)
+- [axe-core rule `frame-title`](https://dequeuniversity.com/rules/axe/4.10/frame-title)

lib/rules/template-require-iframe-title.js

@@ -27,7 +27,17 @@ module.exports = {
       url: 'https://github.com/ember-cli/eslint-plugin-ember/tree/master/docs/rules/template-require-iframe-title.md',
       templateMode: 'both',
     },
-    schema: [],
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          allowWhitespaceOnlyTitle: {
+            type: 'boolean',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
     messages: {
       // Four messageIds (missingTitle, emptyTitle, dynamicFalseTitle,
       // duplicateTitle) for richer diagnostic detail.
@@ -46,6 +56,14 @@ module.exports = {
     },
   },
   create(context) {
+    // Whitespace-only `title="   "` is technically spec-compliant: ACCNAME
+    // 1.2 step 2I (Tooltip) does not whitespace-trim like step 2D
+    // (aria-label) does, so a 3-space accessible name is assigned. That is
+    // useless in practice but not a spec violation. Default behavior flags
+    // it as authoring hygiene; set `allowWhitespaceOnlyTitle: true` to
+    // align with spec/peer behavior.
+    const allowWhitespaceOnlyTitle = Boolean(context.options[0]?.allowWhitespaceOnlyTitle);
+
     // Each entry: { value, node, index }
     //  - value: trimmed title string
     //  - node: original element node for the first occurrence
@@ -76,9 +94,15 @@ module.exports = {
         if (titleAttr.value) {
           switch (titleAttr.value.type) {
             case 'GlimmerTextNode': {
-              const value = titleAttr.value.chars.trim();
+              const raw = titleAttr.value.chars;
+              const value = raw.trim();
               if (value.length === 0) {
-                context.report({ node, messageId: 'emptyTitle' });
+                // Distinguish genuine empty-string (always flagged — not a
+                // string) from whitespace-only (spec-compliant but hygiene
+                // check). Whitespace-only case respects the schema option.
+                if (raw.length === 0 || !allowWhitespaceOnlyTitle) {
+                  context.report({ node, messageId: 'emptyTitle' });
+                }
               } else {
                 // Check for duplicate titles. Reports BOTH the first and the
                 // current occurrence on every collision, sharing a `#N` index

tests/lib/rules/template-require-iframe-title.js

@@ -18,6 +18,11 @@ ruleTester.run('template-require-iframe-title', rule, {
     '<template><iframe title="" aria-hidden /></template>',
     '<template><iframe title="" hidden /></template>',
     '<template><iframe title="foo" /><iframe title="bar" /></template>',
+    // allowWhitespaceOnlyTitle: true — whitespace-only accepted.
+    {
+      code: '<template><iframe title="   " /></template>',
+      options: [{ allowWhitespaceOnlyTitle: true }],
+    },
   ],
   invalid: [
     {
@@ -136,6 +141,21 @@ ruleTester.run('template-require-iframe-title', rule, {
       output: null,
       errors: [{ messageId: 'dynamicFalseTitle' }],
     },
+
+    // Whitespace-only title is flagged by default (authoring hygiene).
+    {
+      code: '<template><iframe title="   " /></template>',
+      output: null,
+      errors: [{ messageId: 'emptyTitle' }],
+    },
+    // Empty-string title is flagged even with allowWhitespaceOnlyTitle: true
+    // (an empty string is not a whitespace string).
+    {
+      code: '<template><iframe title="" /></template>',
+      options: [{ allowWhitespaceOnlyTitle: true }],
+      output: null,
+      errors: [{ messageId: 'emptyTitle' }],
+    },
   ],
 });