diff --git a/docs/rules/template-no-autofocus-attribute.md b/docs/rules/template-no-autofocus-attribute.md index b3bc9bd425..b257beac98 100644 --- 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: ``` +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 + +``` + +`` 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 + +``` + ## 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 index d01c000e18..b63768b9f1 100644 --- 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 `` + * element or is nested (at any depth) inside a `` 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 +// 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,25 +104,40 @@ 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 or inside a + // 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) { @@ -53,12 +145,49 @@ module.exports = { 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 + // 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 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 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 index ad67f03943..08571b62a0 100644 --- 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, { ``, + // 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. + ``, + ``, + // Dialog exception (MDN): autofocus on is recommended. + ``, + // Dialog descendants are also exempt (angular-eslint parity). + ``, + ``, + // Dialog exception also applies to the classic mustache form + // (`{{input autofocus=true}}`) — whether direct child or nested. + ``, + ``, + + // Custom helpers / components taking an `autofocus` prop are opaque — + // we can't know whether the prop forwards to a native + // or is used for something else. Narrow to {{input}} / {{component + // "input"}} which deterministically render native inputs. + '', + '', + '', ], invalid: [ @@ -123,5 +171,110 @@ ruleTester.run('template-no-autofocus-attribute', rule, { }, ], }, + // Value-aware: truthy literals and any dynamic value still flag. + { + code: ``, + output: ``, + errors: [ + { + messageId: 'noAutofocus', + type: 'GlimmerAttrNode', + }, + ], + }, + { + code: ``, + output: ``, + errors: [ + { + messageId: 'noAutofocus', + type: 'GlimmerAttrNode', + }, + ], + }, + { + code: ``, + output: ``, + errors: [ + { + messageId: 'noAutofocus', + type: 'GlimmerAttrNode', + }, + ], + }, + { + code: ``, + output: ``, + errors: [ + { + messageId: 'noAutofocus', + type: 'GlimmerAttrNode', + }, + ], + }, + // Dialog exception only applies within ; siblings elsewhere still flag. + { + code: ``, + output: ``, + 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: ``, + output: ``, + errors: [{ messageId: 'noAutofocus', type: 'GlimmerAttrNode' }], + }, + { + code: ``, + output: ``, + errors: [{ messageId: 'noAutofocus', type: 'GlimmerAttrNode' }], + }, + { + code: ``, + output: null, + errors: [{ messageId: 'noAutofocus' }], + }, ], });