From 068608b22a1ee03b2d43f37e5736c4745ac50eb8 Mon Sep 17 00:00:00 2001
From: LB <mail@lb.ee>
Date: Wed, 23 Oct 2024 11:41:12 +1000
Subject: [PATCH] [New] `interactive-supports-focus`: add basic suggestions

Add basic support for ESlint rule suggestions for the `interactive-supports-focus` for tabIndex values when elements are interactive but do not have implicit focusable browser behaviour.
These are intentionally not auto-fix but simply optional suggestions to help developers resolve their issue.

Fixes #952
See also #951
---
 README.md                                     | 83 ++++++++++---------
 .../rules/interactive-supports-focus-test.js  | 17 +++-
 docs/rules/interactive-supports-focus.md      |  2 +
 src/rules/interactive-supports-focus.js       | 27 ++++++
 4 files changed, 87 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index 44cb16ea7..494a57841 100644
--- a/README.md
+++ b/README.md
@@ -233,49 +233,50 @@ To restrict polymorphic linting to specified components, additionally set `polym
 🚫 Configurations disabled in.\
 ☑️ Set in the `recommended` configuration.\
 🔒 Set in the `strict` configuration.\
+💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).\
 ❌ Deprecated.
 
-| Name                                                                                                         | Description                                                                                                                         | 💼    | 🚫    | ❌  |
-| :----------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :---- | :---- | :- |
-| [accessible-emoji](docs/rules/accessible-emoji.md)                                                           | Enforce emojis are wrapped in `<span>` and provide screen reader access.                                                            |       |       | ❌  |
-| [alt-text](docs/rules/alt-text.md)                                                                           | Enforce all elements that require alternative text have meaningful information to relay back to end user.                           | ☑️ 🔒 |       |    |
-| [anchor-ambiguous-text](docs/rules/anchor-ambiguous-text.md)                                                 | Enforce `<a>` text to not exactly match "click here", "here", "link", or "a link".                                                  |       | ☑️    |    |
-| [anchor-has-content](docs/rules/anchor-has-content.md)                                                       | Enforce all anchors to contain accessible content.                                                                                  | ☑️ 🔒 |       |    |
-| [anchor-is-valid](docs/rules/anchor-is-valid.md)                                                             | Enforce all anchors are valid, navigable elements.                                                                                  | ☑️ 🔒 |       |    |
-| [aria-activedescendant-has-tabindex](docs/rules/aria-activedescendant-has-tabindex.md)                       | Enforce elements with aria-activedescendant are tabbable.                                                                           | ☑️ 🔒 |       |    |
-| [aria-props](docs/rules/aria-props.md)                                                                       | Enforce all `aria-*` props are valid.                                                                                               | ☑️ 🔒 |       |    |
-| [aria-proptypes](docs/rules/aria-proptypes.md)                                                               | Enforce ARIA state and property values are valid.                                                                                   | ☑️ 🔒 |       |    |
-| [aria-role](docs/rules/aria-role.md)                                                                         | Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.                                                     | ☑️ 🔒 |       |    |
-| [aria-unsupported-elements](docs/rules/aria-unsupported-elements.md)                                         | Enforce that elements that do not support ARIA roles, states, and properties do not have those attributes.                          | ☑️ 🔒 |       |    |
-| [autocomplete-valid](docs/rules/autocomplete-valid.md)                                                       | Enforce that autocomplete attributes are used correctly.                                                                            | ☑️ 🔒 |       |    |
-| [click-events-have-key-events](docs/rules/click-events-have-key-events.md)                                   | Enforce a clickable non-interactive element has at least one keyboard event listener.                                               | ☑️ 🔒 |       |    |
-| [control-has-associated-label](docs/rules/control-has-associated-label.md)                                   | Enforce that a control (an interactive element) has a text label.                                                                   |       | ☑️ 🔒 |    |
-| [heading-has-content](docs/rules/heading-has-content.md)                                                     | Enforce heading (`h1`, `h2`, etc) elements contain accessible content.                                                              | ☑️ 🔒 |       |    |
-| [html-has-lang](docs/rules/html-has-lang.md)                                                                 | Enforce `<html>` element has `lang` prop.                                                                                           | ☑️ 🔒 |       |    |
-| [iframe-has-title](docs/rules/iframe-has-title.md)                                                           | Enforce iframe elements have a title attribute.                                                                                     | ☑️ 🔒 |       |    |
-| [img-redundant-alt](docs/rules/img-redundant-alt.md)                                                         | Enforce `<img>` alt prop does not contain the word "image", "picture", or "photo".                                                  | ☑️ 🔒 |       |    |
-| [interactive-supports-focus](docs/rules/interactive-supports-focus.md)                                       | Enforce that elements with interactive handlers like `onClick` must be focusable.                                                   | ☑️ 🔒 |       |    |
-| [label-has-associated-control](docs/rules/label-has-associated-control.md)                                   | Enforce that a `label` tag has a text label and an associated control.                                                              | ☑️ 🔒 |       |    |
-| [label-has-for](docs/rules/label-has-for.md)                                                                 | Enforce that `<label>` elements have the `htmlFor` prop.                                                                            |       | ☑️ 🔒 | ❌  |
-| [lang](docs/rules/lang.md)                                                                                   | Enforce lang attribute has a valid value.                                                                                           |       |       |    |
-| [media-has-caption](docs/rules/media-has-caption.md)                                                         | Enforces that `<audio>` and `<video>` elements must have a `<track>` for captions.                                                  | ☑️ 🔒 |       |    |
-| [mouse-events-have-key-events](docs/rules/mouse-events-have-key-events.md)                                   | Enforce that `onMouseOver`/`onMouseOut` are accompanied by `onFocus`/`onBlur` for keyboard-only users.                              | ☑️ 🔒 |       |    |
-| [no-access-key](docs/rules/no-access-key.md)                                                                 | Enforce that the `accessKey` prop is not used on any element to avoid complications with keyboard commands used by a screen reader. | ☑️ 🔒 |       |    |
-| [no-aria-hidden-on-focusable](docs/rules/no-aria-hidden-on-focusable.md)                                     | Disallow `aria-hidden="true"` from being set on focusable elements.                                                                 |       |       |    |
-| [no-autofocus](docs/rules/no-autofocus.md)                                                                   | Enforce autoFocus prop is not used.                                                                                                 | ☑️ 🔒 |       |    |
-| [no-distracting-elements](docs/rules/no-distracting-elements.md)                                             | Enforce distracting elements are not used.                                                                                          | ☑️ 🔒 |       |    |
-| [no-interactive-element-to-noninteractive-role](docs/rules/no-interactive-element-to-noninteractive-role.md) | Interactive elements should not be assigned non-interactive roles.                                                                  | ☑️ 🔒 |       |    |
-| [no-noninteractive-element-interactions](docs/rules/no-noninteractive-element-interactions.md)               | Non-interactive elements should not be assigned mouse or keyboard event listeners.                                                  | ☑️ 🔒 |       |    |
-| [no-noninteractive-element-to-interactive-role](docs/rules/no-noninteractive-element-to-interactive-role.md) | Non-interactive elements should not be assigned interactive roles.                                                                  | ☑️ 🔒 |       |    |
-| [no-noninteractive-tabindex](docs/rules/no-noninteractive-tabindex.md)                                       | `tabIndex` should only be declared on interactive elements.                                                                         | ☑️ 🔒 |       |    |
-| [no-onchange](docs/rules/no-onchange.md)                                                                     | Enforce usage of `onBlur` over `onChange` on select menus for accessibility.                                                        |       |       | ❌  |
-| [no-redundant-roles](docs/rules/no-redundant-roles.md)                                                       | Enforce explicit role property is not the same as implicit/default role property on element.                                        | ☑️ 🔒 |       |    |
-| [no-static-element-interactions](docs/rules/no-static-element-interactions.md)                               | Enforce that non-interactive, visible elements (such as `<div>`) that have click handlers use the role attribute.                   | ☑️ 🔒 |       |    |
-| [prefer-tag-over-role](docs/rules/prefer-tag-over-role.md)                                                   | Enforces using semantic DOM elements over the ARIA `role` property.                                                                 |       |       |    |
-| [role-has-required-aria-props](docs/rules/role-has-required-aria-props.md)                                   | Enforce that elements with ARIA roles must have all required attributes for that role.                                              | ☑️ 🔒 |       |    |
-| [role-supports-aria-props](docs/rules/role-supports-aria-props.md)                                           | Enforce that elements with explicit or implicit roles defined contain only `aria-*` properties supported by that `role`.            | ☑️ 🔒 |       |    |
-| [scope](docs/rules/scope.md)                                                                                 | Enforce `scope` prop is only used on `<th>` elements.                                                                               | ☑️ 🔒 |       |    |
-| [tabindex-no-positive](docs/rules/tabindex-no-positive.md)                                                   | Enforce `tabIndex` value is not greater than zero.                                                                                  | ☑️ 🔒 |       |    |
+| Name                                                                                                         | Description                                                                                                                         | 💼    | 🚫    | 💡 | ❌  |
+| :----------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :---- | :---- | :- | :- |
+| [accessible-emoji](docs/rules/accessible-emoji.md)                                                           | Enforce emojis are wrapped in `<span>` and provide screen reader access.                                                            |       |       |    | ❌  |
+| [alt-text](docs/rules/alt-text.md)                                                                           | Enforce all elements that require alternative text have meaningful information to relay back to end user.                           | ☑️ 🔒 |       |    |    |
+| [anchor-ambiguous-text](docs/rules/anchor-ambiguous-text.md)                                                 | Enforce `<a>` text to not exactly match "click here", "here", "link", or "a link".                                                  |       | ☑️    |    |    |
+| [anchor-has-content](docs/rules/anchor-has-content.md)                                                       | Enforce all anchors to contain accessible content.                                                                                  | ☑️ 🔒 |       |    |    |
+| [anchor-is-valid](docs/rules/anchor-is-valid.md)                                                             | Enforce all anchors are valid, navigable elements.                                                                                  | ☑️ 🔒 |       |    |    |
+| [aria-activedescendant-has-tabindex](docs/rules/aria-activedescendant-has-tabindex.md)                       | Enforce elements with aria-activedescendant are tabbable.                                                                           | ☑️ 🔒 |       |    |    |
+| [aria-props](docs/rules/aria-props.md)                                                                       | Enforce all `aria-*` props are valid.                                                                                               | ☑️ 🔒 |       |    |    |
+| [aria-proptypes](docs/rules/aria-proptypes.md)                                                               | Enforce ARIA state and property values are valid.                                                                                   | ☑️ 🔒 |       |    |    |
+| [aria-role](docs/rules/aria-role.md)                                                                         | Enforce that elements with ARIA roles must use a valid, non-abstract ARIA role.                                                     | ☑️ 🔒 |       |    |    |
+| [aria-unsupported-elements](docs/rules/aria-unsupported-elements.md)                                         | Enforce that elements that do not support ARIA roles, states, and properties do not have those attributes.                          | ☑️ 🔒 |       |    |    |
+| [autocomplete-valid](docs/rules/autocomplete-valid.md)                                                       | Enforce that autocomplete attributes are used correctly.                                                                            | ☑️ 🔒 |       |    |    |
+| [click-events-have-key-events](docs/rules/click-events-have-key-events.md)                                   | Enforce a clickable non-interactive element has at least one keyboard event listener.                                               | ☑️ 🔒 |       |    |    |
+| [control-has-associated-label](docs/rules/control-has-associated-label.md)                                   | Enforce that a control (an interactive element) has a text label.                                                                   |       | ☑️ 🔒 |    |    |
+| [heading-has-content](docs/rules/heading-has-content.md)                                                     | Enforce heading (`h1`, `h2`, etc) elements contain accessible content.                                                              | ☑️ 🔒 |       |    |    |
+| [html-has-lang](docs/rules/html-has-lang.md)                                                                 | Enforce `<html>` element has `lang` prop.                                                                                           | ☑️ 🔒 |       |    |    |
+| [iframe-has-title](docs/rules/iframe-has-title.md)                                                           | Enforce iframe elements have a title attribute.                                                                                     | ☑️ 🔒 |       |    |    |
+| [img-redundant-alt](docs/rules/img-redundant-alt.md)                                                         | Enforce `<img>` alt prop does not contain the word "image", "picture", or "photo".                                                  | ☑️ 🔒 |       |    |    |
+| [interactive-supports-focus](docs/rules/interactive-supports-focus.md)                                       | Enforce that elements with interactive handlers like `onClick` must be focusable.                                                   | ☑️ 🔒 |       | 💡 |    |
+| [label-has-associated-control](docs/rules/label-has-associated-control.md)                                   | Enforce that a `label` tag has a text label and an associated control.                                                              | ☑️ 🔒 |       |    |    |
+| [label-has-for](docs/rules/label-has-for.md)                                                                 | Enforce that `<label>` elements have the `htmlFor` prop.                                                                            |       | ☑️ 🔒 |    | ❌  |
+| [lang](docs/rules/lang.md)                                                                                   | Enforce lang attribute has a valid value.                                                                                           |       |       |    |    |
+| [media-has-caption](docs/rules/media-has-caption.md)                                                         | Enforces that `<audio>` and `<video>` elements must have a `<track>` for captions.                                                  | ☑️ 🔒 |       |    |    |
+| [mouse-events-have-key-events](docs/rules/mouse-events-have-key-events.md)                                   | Enforce that `onMouseOver`/`onMouseOut` are accompanied by `onFocus`/`onBlur` for keyboard-only users.                              | ☑️ 🔒 |       |    |    |
+| [no-access-key](docs/rules/no-access-key.md)                                                                 | Enforce that the `accessKey` prop is not used on any element to avoid complications with keyboard commands used by a screen reader. | ☑️ 🔒 |       |    |    |
+| [no-aria-hidden-on-focusable](docs/rules/no-aria-hidden-on-focusable.md)                                     | Disallow `aria-hidden="true"` from being set on focusable elements.                                                                 |       |       |    |    |
+| [no-autofocus](docs/rules/no-autofocus.md)                                                                   | Enforce autoFocus prop is not used.                                                                                                 | ☑️ 🔒 |       |    |    |
+| [no-distracting-elements](docs/rules/no-distracting-elements.md)                                             | Enforce distracting elements are not used.                                                                                          | ☑️ 🔒 |       |    |    |
+| [no-interactive-element-to-noninteractive-role](docs/rules/no-interactive-element-to-noninteractive-role.md) | Interactive elements should not be assigned non-interactive roles.                                                                  | ☑️ 🔒 |       |    |    |
+| [no-noninteractive-element-interactions](docs/rules/no-noninteractive-element-interactions.md)               | Non-interactive elements should not be assigned mouse or keyboard event listeners.                                                  | ☑️ 🔒 |       |    |    |
+| [no-noninteractive-element-to-interactive-role](docs/rules/no-noninteractive-element-to-interactive-role.md) | Non-interactive elements should not be assigned interactive roles.                                                                  | ☑️ 🔒 |       |    |    |
+| [no-noninteractive-tabindex](docs/rules/no-noninteractive-tabindex.md)                                       | `tabIndex` should only be declared on interactive elements.                                                                         | ☑️ 🔒 |       |    |    |
+| [no-onchange](docs/rules/no-onchange.md)                                                                     | Enforce usage of `onBlur` over `onChange` on select menus for accessibility.                                                        |       |       |    | ❌  |
+| [no-redundant-roles](docs/rules/no-redundant-roles.md)                                                       | Enforce explicit role property is not the same as implicit/default role property on element.                                        | ☑️ 🔒 |       |    |    |
+| [no-static-element-interactions](docs/rules/no-static-element-interactions.md)                               | Enforce that non-interactive, visible elements (such as `<div>`) that have click handlers use the role attribute.                   | ☑️ 🔒 |       |    |    |
+| [prefer-tag-over-role](docs/rules/prefer-tag-over-role.md)                                                   | Enforces using semantic DOM elements over the ARIA `role` property.                                                                 |       |       |    |    |
+| [role-has-required-aria-props](docs/rules/role-has-required-aria-props.md)                                   | Enforce that elements with ARIA roles must have all required attributes for that role.                                              | ☑️ 🔒 |       |    |    |
+| [role-supports-aria-props](docs/rules/role-supports-aria-props.md)                                           | Enforce that elements with explicit or implicit roles defined contain only `aria-*` properties supported by that `role`.            | ☑️ 🔒 |       |    |    |
+| [scope](docs/rules/scope.md)                                                                                 | Enforce `scope` prop is only used on `<th>` elements.                                                                               | ☑️ 🔒 |       |    |    |
+| [tabindex-no-positive](docs/rules/tabindex-no-positive.md)                                                   | Enforce `tabIndex` value is not greater than zero.                                                                                  | ☑️ 🔒 |       |    |    |
 
 <!-- end auto-generated rules list -->
 
diff --git a/__tests__/src/rules/interactive-supports-focus-test.js b/__tests__/src/rules/interactive-supports-focus-test.js
index 3220942ac..7635e20c1 100644
--- a/__tests__/src/rules/interactive-supports-focus-test.js
+++ b/__tests__/src/rules/interactive-supports-focus-test.js
@@ -35,6 +35,7 @@ function template(strings, ...keys) {
 const ruleName = 'interactive-supports-focus';
 const type = 'JSXOpeningElement';
 const codeTemplate = template`<${0} role="${1}" ${2}={() => void 0} />`;
+const fixedTemplate = template`<${0} tabIndex={${1}} role="${2}" ${3}={() => void 0} />`;
 const tabindexTemplate = template`<${0} role="${1}" ${2}={() => void 0} tabIndex="0" />`;
 const tabbableTemplate = template`Elements with the '${0}' interactive role must be tabbable.`;
 const focusableTemplate = template`Elements with the '${0}' interactive role must be focusable.`;
@@ -47,7 +48,14 @@ const componentsSettings = {
   },
 };
 
-const buttonError = { message: tabbableTemplate('button'), type };
+const buttonError = {
+  message: tabbableTemplate('button'),
+  suggestions: [{
+    desc: 'Add `tabIndex={0}` to make the element focusable in sequential keyboard navigation.',
+    output: '<Div tabIndex={0} onClick={() => void 0} role="button" />',
+  }],
+  type,
+};
 
 const recommendedOptions = configs.recommended.rules[`jsx-a11y/${ruleName}`][1] || {};
 
@@ -202,6 +210,13 @@ const failReducer = (roles, handlers, messageTemplate) => (
         errors: [{
           type,
           message: messageTemplate(role),
+          suggestions: [{
+            desc: 'Add `tabIndex={0}` to make the element focusable in sequential keyboard navigation.',
+            output: fixedTemplate(element, '0', role, handler),
+          }].concat(messageTemplate === focusableTemplate ? [{
+            desc: 'Add `tabIndex={-1}` to make the element focusable but not reachable via sequential keyboard navigation.',
+            output: fixedTemplate(element, '-1', role, handler),
+          }] : []),
         }],
       })))
     ), []))
diff --git a/docs/rules/interactive-supports-focus.md b/docs/rules/interactive-supports-focus.md
index 2e896b0e3..4962f67b9 100644
--- a/docs/rules/interactive-supports-focus.md
+++ b/docs/rules/interactive-supports-focus.md
@@ -2,6 +2,8 @@
 
 💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
 
+💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
+
 <!-- end auto-generated rule header -->
 
 Elements with an interactive role and interaction handlers (mouse or key press) must be focusable.
diff --git a/src/rules/interactive-supports-focus.js b/src/rules/interactive-supports-focus.js
index ce6cb4482..736d703ac 100644
--- a/src/rules/interactive-supports-focus.js
+++ b/src/rules/interactive-supports-focus.js
@@ -53,6 +53,11 @@ export default ({
       url: 'https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/tree/HEAD/docs/rules/interactive-supports-focus.md',
       description: 'Enforce that elements with interactive handlers like `onClick` must be focusable.',
     },
+    hasSuggestions: true,
+    messages: {
+      'tabIndex=0': 'Add `tabIndex={0}` to make the element focusable in sequential keyboard navigation.',
+      'tabIndex=-1': 'Add `tabIndex={-1}` to make the element focusable but not reachable via sequential keyboard navigation.',
+    },
     schema: [schema],
   },
 
@@ -99,12 +104,34 @@ export default ({
             context.report({
               node,
               message: `Elements with the '${role}' interactive role must be tabbable.`,
+              suggest: [
+                {
+                  messageId: 'tabIndex=0',
+                  fix(fixer) {
+                    return fixer.insertTextAfter(node.name, ' tabIndex={0}');
+                  },
+                },
+              ],
             });
           } else {
             // Focusable, tabIndex = -1 or 0
             context.report({
               node,
               message: `Elements with the '${role}' interactive role must be focusable.`,
+              suggest: [
+                {
+                  messageId: 'tabIndex=0',
+                  fix(fixer) {
+                    return fixer.insertTextAfter(node.name, ' tabIndex={0}');
+                  },
+                },
+                {
+                  messageId: 'tabIndex=-1',
+                  fix(fixer) {
+                    return fixer.insertTextAfter(node.name, ' tabIndex={-1}');
+                  },
+                },
+              ],
             });
           }
         }