Merge pull request #2743 from johanrd/fix/autofocus-value-aware-and-dialog

NullVoxPopuli · web-flow · commit 30ce5dfd6996 · 2026-04-25T12:11:11.000-04:00
fix: template-no-autofocus-attribute — value-aware + &lt;dialog&gt; exception
diff --git a/docs/rules/template-no-autofocus-attribute.md b/docs/rules/template-no-autofocus-attribute.md
@@ -40,6 +40,34 @@ Examples of **correct** code for this rule:
 </template>
 ```
 
+Explicit opt-out via a mustache boolean `false` is allowed — this is the
+only form that statically guarantees no rendered `autofocus` attribute
+(Glimmer VM normalizes `{{false}}` to attribute removal). The string
+`autofocus="false"` is still flagged per HTML boolean-attribute semantics
+(any attribute presence, including the string `"false"`, enables autofocus).
+
+```gjs
+<template>
+  <input autofocus={{false}} />
+  {{!-- element syntax: the mustache-boolean form --}}
+
+  {{input autofocus=false}}
+  {{!-- mustache syntax: the hash-pair form --}}
+</template>
+```
+
+`<dialog>` and its descendants are exempt. A dialog is expected to focus its
+initial element on open, per
+[MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog):
+
+```gjs
+<template>
+  <dialog>
+    <button autofocus>Close</button>
+  </dialog>
+</template>
+```
+
 ## When Not To Use It
 
 If you need to autofocus for specific accessibility or UX requirements and have thoroughly tested with assistive technologies, you may disable this rule for those specific cases.
diff --git a/lib/rules/template-no-autofocus-attribute.js b/lib/rules/template-no-autofocus-attribute.js
@@ -1,3 +1,80 @@
+/**
+ * `autofocus` is a boolean HTML attribute. Per the HTML spec, any presence
+ * (including `autofocus="false"`, `autofocus=""`, `autofocus="autofocus"`)
+ * means the element will auto-focus. Only the genuine absence of the
+ * attribute turns off auto-focus.
+ *
+ * jsx-a11y's `no-autofocus` treats `autofocus={false}` / `autofocus="false"`
+ * as opt-outs — that is a peer-plugin convention that diverges from HTML
+ * boolean-attribute semantics. vue-a11y and lit-a11y are presence-based,
+ * consistent with the spec. We follow the spec.
+ *
+ * The only exception is a boolean-literal `false` — in element syntax
+ * written as `autofocus={{false}}`, and in mustache hash syntax written as
+ * `{{input autofocus=false}}`. Both forms express intent to omit the
+ * attribute conditionally, and the rendered HTML will have no autofocus
+ * attribute. Treat both literal-false cases as opt-out.
+ *
+ * Verified against Glimmer VM's attribute-normalization source:
+ * glimmer-vm/packages/@glimmer/runtime/lib/vm/attributes/dynamic.ts —
+ * `normalizeValue` returns `null` for `false | undefined | null`, and
+ * `SimpleDynamicAttribute.update()` calls `element.removeAttribute(name)`
+ * when the normalized value is null. So `autofocus={{false}}` renders
+ * with the attribute entirely absent from the DOM.
+ */
+function isMustacheBooleanFalse(value) {
+  if (value?.type !== 'GlimmerMustacheStatement') {
+    return false;
+  }
+  const expr = value.path;
+  return expr?.type === 'GlimmerBooleanLiteral' && expr.value === false;
+}
+
+/**
+ * Returns true when the given node (a GlimmerElementNode OR a
+ * GlimmerMustacheStatement, e.g. `{{input autofocus=true}}`) is a `<dialog>`
+ * element or is nested (at any depth) inside a `<dialog>` element. Per MDN,
+ * autofocus on (or within) a dialog is recommended because a dialog should
+ * focus its initial element when opened.
+ *
+ * https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog
+ */
+// Returns true for `{{input ...}}` and `{{component "input" ...}}` mustache
+// invocations — the only built-ins that deterministically render a native
+// <input> with forwarded attributes.
+function isNativeInputHelper(node) {
+  const path = node.path;
+  if (!path) {
+    return false;
+  }
+  // Direct invocation: `{{input ...}}`.
+  if (path.type === 'GlimmerPathExpression' && path.original === 'input') {
+    return true;
+  }
+  // Contextual component: `{{component "input" ...}}`.
+  if (path.type === 'GlimmerPathExpression' && path.original === 'component') {
+    const firstParam = node.params && node.params[0];
+    if (firstParam && firstParam.type === 'GlimmerStringLiteral' && firstParam.value === 'input') {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isInsideDialog(node) {
+  if (node.type === 'GlimmerElementNode' && node.tag === 'dialog') {
+    return true;
+  }
+  let ancestor = node.parent;
+  while (ancestor) {
+    if (ancestor.type === 'GlimmerElementNode' && ancestor.tag === 'dialog') {
+      return true;
+    }
+    ancestor = ancestor.parent;
+  }
+  return false;
+}
+
 /** @type {import('eslint').Rule.RuleModule} */
 module.exports = {
   meta: {
@@ -27,38 +104,90 @@ module.exports = {
       GlimmerElementNode(node) {
         const autofocusAttr = node.attributes?.find((attr) => attr.name === 'autofocus');
 
-        if (autofocusAttr) {
-          context.report({
-            node: autofocusAttr,
-            messageId: 'noAutofocus',
-            fix(fixer) {
-              const sourceCode = context.sourceCode;
-              const text = sourceCode.getText();
-              const attrStart = autofocusAttr.range[0];
-              const attrEnd = autofocusAttr.range[1];
-
-              let removeStart = attrStart;
-              while (removeStart > 0 && /\s/.test(text[removeStart - 1])) {
-                removeStart--;
-              }
-
-              return fixer.removeRange([removeStart, attrEnd]);
-            },
-          });
+        if (!autofocusAttr) {
+          return;
+        }
+
+        // Mustache boolean-literal `autofocus={{false}}` renders no attribute
+        // at all — the only statically-known opt-out consistent with HTML
+        // boolean-attribute semantics.
+        if (isMustacheBooleanFalse(autofocusAttr.value)) {
+          return;
+        }
+
+        // MDN dialog exception: autofocus on a <dialog> or inside a <dialog>
+        // is recommended behavior, not an accessibility defect.
+        if (isInsideDialog(node)) {
+          return;
         }
+
+        context.report({
+          node: autofocusAttr,
+          messageId: 'noAutofocus',
+          fix(fixer) {
+            const sourceCode = context.sourceCode;
+            const text = sourceCode.getText();
+            const attrStart = autofocusAttr.range[0];
+            const attrEnd = autofocusAttr.range[1];
+
+            let removeStart = attrStart;
+            while (removeStart > 0 && /\s/.test(text[removeStart - 1])) {
+              removeStart--;
+            }
+
+            return fixer.removeRange([removeStart, attrEnd]);
+          },
+        });
       },
 
       GlimmerMustacheStatement(node) {
         if (!node.hash || !node.hash.pairs) {
           return;
         }
         const autofocusPair = node.hash.pairs.find((pair) => pair.key === 'autofocus');
-        if (autofocusPair) {
-          context.report({
-            node: autofocusPair,
-            messageId: 'noAutofocus',
-          });
+        if (!autofocusPair) {
+          return;
+        }
+
+        // Narrow to helpers that deterministically render a native `autofocus`
+        // attribute. The rule's purpose is the HTML attribute; arbitrary
+        // components taking an `autofocus` prop are opaque — we can't tell
+        // statically whether that prop forwards to HTML or is used for
+        // something else.
+        //   - `{{input ...}}` — Ember's classic input helper renders a native
+        //     <input> with forwarded attributes.
+        //   - `{{component "input" ...}}` — contextual component resolution
+        //     points at the same helper.
+        //
+        // FUTURE: when type-aware linting lands (e.g., Glint integration or
+        // a template-type-check step), we can resolve custom components that
+        // forward `autofocus` to a native <input> and flag those too. For now
+        // we stay conservative to avoid false positives on unrelated helpers
+        // that happen to take an `autofocus` prop.
+        if (!isNativeInputHelper(node)) {
+          return;
+        }
+
+        // Mustache hash-pair `{{input autofocus=false}}` — boolean literal
+        // false at the hash-pair level is unambiguous and renders no attr.
+        // Note: `autofocus="false"` in mustache syntax IS still flagged — per
+        // HTML boolean-attribute semantics the string "false" is truthy; it
+        // is only jsx-a11y that carves that form out.
+        const pairValue = autofocusPair.value;
+        if (pairValue?.type === 'GlimmerBooleanLiteral' && pairValue.value === false) {
+          return;
+        }
+
+        // MDN dialog exception: autofocus on a mustache component/helper
+        // nested inside a <dialog> is recommended behavior, not a defect.
+        if (isInsideDialog(node)) {
+          return;
         }
+
+        context.report({
+          node: autofocusPair,
+          messageId: 'noAutofocus',
+        });
       },
     };
   },
diff --git a/tests/lib/rules/template-no-autofocus-attribute.js b/tests/lib/rules/template-no-autofocus-attribute.js
@@ -22,6 +22,54 @@ ruleTester.run('template-no-autofocus-attribute', rule, {
     `<template>
       <button>Click me</button>
     </template>`,
+    // Mustache boolean-literal forms render NO attribute when the literal
+    // is false — these are the statically-known opt-outs that align with
+    // HTML boolean-attribute semantics.
+    `<template>
+      <input autofocus={{false}} />
+    </template>`,
+    `<template>
+      {{input autofocus=false}}
+    </template>`,
+    // Dialog exception (MDN): autofocus on <dialog> is recommended.
+    `<template>
+      <dialog autofocus></dialog>
+    </template>`,
+    // Dialog descendants are also exempt (angular-eslint parity).
+    `<template>
+      <dialog>
+        <button autofocus>Close</button>
+      </dialog>
+    </template>`,
+    `<template>
+      <dialog>
+        <div>
+          <input autofocus />
+        </div>
+      </dialog>
+    </template>`,
+    // Dialog exception also applies to the classic mustache form
+    // (`{{input autofocus=true}}`) — whether direct child or nested.
+    `<template>
+      <dialog>
+        {{input autofocus=true}}
+      </dialog>
+    </template>`,
+    `<template>
+      <dialog>
+        <div>
+          {{input autofocus=true}}
+        </div>
+      </dialog>
+    </template>`,
+
+    // Custom helpers / components taking an `autofocus` prop are opaque —
+    // we can't know whether the prop forwards to a native <input autofocus>
+    // or is used for something else. Narrow to {{input}} / {{component
+    // "input"}} which deterministically render native inputs.
+    '<template>{{my-wrapper autofocus=true}}</template>',
+    '<template>{{some-component autofocus=true name="foo"}}</template>',
+    '<template>{{component "some-other-helper" autofocus=true}}</template>',
   ],
 
   invalid: [
@@ -123,5 +171,110 @@ ruleTester.run('template-no-autofocus-attribute', rule, {
         },
       ],
     },
+    // Value-aware: truthy literals and any dynamic value still flag.
+    {
+      code: `<template>
+        <input autofocus="true" />
+      </template>`,
+      output: `<template>
+        <input />
+      </template>`,
+      errors: [
+        {
+          messageId: 'noAutofocus',
+          type: 'GlimmerAttrNode',
+        },
+      ],
+    },
+    {
+      code: `<template>
+        <input autofocus={{true}} />
+      </template>`,
+      output: `<template>
+        <input />
+      </template>`,
+      errors: [
+        {
+          messageId: 'noAutofocus',
+          type: 'GlimmerAttrNode',
+        },
+      ],
+    },
+    {
+      code: `<template>
+        <input autofocus={{"true"}} />
+      </template>`,
+      output: `<template>
+        <input />
+      </template>`,
+      errors: [
+        {
+          messageId: 'noAutofocus',
+          type: 'GlimmerAttrNode',
+        },
+      ],
+    },
+    {
+      code: `<template>
+        <input autofocus={{this.shouldFocus}} />
+      </template>`,
+      output: `<template>
+        <input />
+      </template>`,
+      errors: [
+        {
+          messageId: 'noAutofocus',
+          type: 'GlimmerAttrNode',
+        },
+      ],
+    },
+    // Dialog exception only applies within <dialog>; siblings elsewhere still flag.
+    {
+      code: `<template>
+        <section>
+          <button autofocus>Focus</button>
+        </section>
+      </template>`,
+      output: `<template>
+        <section>
+          <button>Focus</button>
+        </section>
+      </template>`,
+      errors: [
+        {
+          messageId: 'noAutofocus',
+          type: 'GlimmerAttrNode',
+        },
+      ],
+    },
+
+    // Per HTML boolean-attribute semantics, the string "false" / mustache
+    // string "false" / hash-pair string "false" are all TRUTHY. Only the
+    // mustache boolean-literal {{false}} renders no attribute.
+    {
+      code: `<template>
+        <input autofocus="false" />
+      </template>`,
+      output: `<template>
+        <input />
+      </template>`,
+      errors: [{ messageId: 'noAutofocus', type: 'GlimmerAttrNode' }],
+    },
+    {
+      code: `<template>
+        <input autofocus={{"false"}} />
+      </template>`,
+      output: `<template>
+        <input />
+      </template>`,
+      errors: [{ messageId: 'noAutofocus', type: 'GlimmerAttrNode' }],
+    },
+    {
+      code: `<template>
+        {{input autofocus="false"}}
+      </template>`,
+      output: null,
+      errors: [{ messageId: 'noAutofocus' }],
+    },
   ],
 });
