From 3f92cd4b689e437bb9efe6a9fe873501ddf76bf2 Mon Sep 17 00:00:00 2001
From: Cam McHenry <camchenry@users.noreply.github.com>
Date: Wed, 28 Aug 2024 04:55:25 -0400
Subject: [PATCH] Add `prefer-action-list-item-onselect` (#211)

* Add rule

* Add tests

* Add rule to recommended config

* Add autofixer

* Add docs

* Add changeset

* Fix typo

* Use replaceText instead of replaceTextRange

---------

Co-authored-by: Ian Sanders <iansan5653@github.com>
---
 .changeset/sixty-spiders-build.md             |  5 ++
 .../rules/prefer-action-list-item-onselect.md | 37 ++++++++++
 src/configs/recommended.js                    |  1 +
 src/index.js                                  |  1 +
 .../prefer-action-list-item-onselect.test.js  | 67 +++++++++++++++++++
 src/rules/prefer-action-list-item-onselect.js | 67 +++++++++++++++++++
 6 files changed, 178 insertions(+)
 create mode 100644 .changeset/sixty-spiders-build.md
 create mode 100644 docs/rules/prefer-action-list-item-onselect.md
 create mode 100644 src/rules/__tests__/prefer-action-list-item-onselect.test.js
 create mode 100644 src/rules/prefer-action-list-item-onselect.js

diff --git a/.changeset/sixty-spiders-build.md b/.changeset/sixty-spiders-build.md
new file mode 100644
index 0000000..5bedea5
--- /dev/null
+++ b/.changeset/sixty-spiders-build.md
@@ -0,0 +1,5 @@
+---
+'eslint-plugin-primer-react': major
+---
+
+[Breaking] Adds `prefer-action-list-item-onselect` lint rule and enables it by default. This may raise new auto-fixable lint errors or type-checking errors in existing codebases.
diff --git a/docs/rules/prefer-action-list-item-onselect.md b/docs/rules/prefer-action-list-item-onselect.md
new file mode 100644
index 0000000..a280475
--- /dev/null
+++ b/docs/rules/prefer-action-list-item-onselect.md
@@ -0,0 +1,37 @@
+# Prefer using `onSelect` instead of `onClick` for `ActionList.Item` components (`prefer-action-list-item-onselect`)
+
+🔧 The `--fix` option on the [ESLint CLI](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.
+
+## Rule details
+
+When using the `onClick` attribute on `ActionList.Item` components, this callback only fires when a user clicks on the element with a mouse. If the user navigates to the element with a keyboard and presses the `Enter` key, the callback will not fire. This produces an inaccessible experience for keyboard users.
+
+Using `onSelect` will lead to a more accessible experience for keyboard users compared to using `onClick`.
+
+This rule is generally auto-fixable, though you may encounter type checking errors that result from not properly handling keyboard events which are not part of the `onSelect` callback signature.
+
+👎 Examples of **incorrect** code for this rule:
+
+```jsx
+<ActionList.Item onClick={handleClick} />
+<ActionList.Item
+  aria-label="Edit item 1"
+  onClick={(event) => {
+    event.preventDefault()
+    handleClick()
+  }}
+/>
+```
+
+👍 Examples of **correct** code for this rule:
+
+```jsx
+<ActionList.Item onSelect={handleClick} />
+<ActionList.Item
+  aria-label="Edit item 1"
+  onSelect={(event) => {
+    event.preventDefault()
+    handleClick()
+  }}
+/>
+```
diff --git a/src/configs/recommended.js b/src/configs/recommended.js
index b7cc948..3bb02d2 100644
--- a/src/configs/recommended.js
+++ b/src/configs/recommended.js
@@ -19,6 +19,7 @@ module.exports = {
     'primer-react/a11y-remove-disable-tooltip': 'error',
     'primer-react/a11y-use-next-tooltip': 'error',
     'primer-react/no-unnecessary-components': 'error',
+    'primer-react/prefer-action-list-item-onselect': 'error',
   },
   settings: {
     github: {
diff --git a/src/index.js b/src/index.js
index 5e4a328..9d5e7aa 100644
--- a/src/index.js
+++ b/src/index.js
@@ -12,6 +12,7 @@ module.exports = {
     'a11y-use-next-tooltip': require('./rules/a11y-use-next-tooltip'),
     'use-deprecated-from-deprecated': require('./rules/use-deprecated-from-deprecated'),
     'primer-react/no-unnecessary-components': require('./rules/no-unnecessary-components'),
+    'primer-react/prefer-action-list-item-onselect': require('./rules/prefer-action-list-item-onselect'),
   },
   configs: {
     recommended: require('./configs/recommended'),
diff --git a/src/rules/__tests__/prefer-action-list-item-onselect.test.js b/src/rules/__tests__/prefer-action-list-item-onselect.test.js
new file mode 100644
index 0000000..4e8a8c9
--- /dev/null
+++ b/src/rules/__tests__/prefer-action-list-item-onselect.test.js
@@ -0,0 +1,67 @@
+const {RuleTester} = require('@typescript-eslint/rule-tester')
+const rule = require('../prefer-action-list-item-onselect')
+
+const ruleTester = new RuleTester({
+  parser: require.resolve('@typescript-eslint/parser'),
+  parserOptions: {
+    ecmaVersion: 2018,
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+})
+
+ruleTester.run('prefer-action-list-item-onselect', rule, {
+  valid: [
+    {code: `<ActionList.Item onSelect={() => console.log(1)} />`},
+    {code: `<ActionList.Item onSelect={() => console.log(1)} onClick={() => console.log(1)} />`},
+    {code: `<Other onClick={() => console.log(1)} />`},
+    {code: `<Button onClick={onSelect} />`},
+    {code: `<Button onSelect={onClick} />`},
+    {code: `<ActionList.Item onClick={() => console.log(1)} onKeyDown={() => console.log(1)} />`},
+    {code: `<ActionList.Item onClick={() => console.log(1)} onKeyUp={() => console.log(1)} />`},
+    // For now, we are not handling spread attributes as this is much less common
+    {code: `<ActionList.Item {...onClick} />`},
+  ],
+  invalid: [
+    {
+      code: `<ActionList.Item onClick={() => console.log(1)} />`,
+      errors: [{messageId: 'prefer-action-list-item-onselect'}],
+      output: `<ActionList.Item onSelect={() => console.log(1)} />`,
+    },
+    {
+      code: `<ActionList.Item aria-label="Edit item 1" onClick={() => console.log(1)} />`,
+      errors: [{messageId: 'prefer-action-list-item-onselect'}],
+      output: `<ActionList.Item aria-label="Edit item 1" onSelect={() => console.log(1)} />`,
+    },
+    {
+      code: `<ActionList.Item aria-label="Edit item 1" onClick={onClick} />`,
+      errors: [{messageId: 'prefer-action-list-item-onselect'}],
+      output: `<ActionList.Item aria-label="Edit item 1" onSelect={onClick} />`,
+    },
+    {
+      code: `<ActionList.Item
+  aria-label="Edit item 1"
+  onClick={(event) => {
+    event.preventDefault()
+    handleClick()
+  }}
+/>`,
+      errors: [{messageId: 'prefer-action-list-item-onselect'}],
+      output: `<ActionList.Item
+  aria-label="Edit item 1"
+  onSelect={(event) => {
+    event.preventDefault()
+    handleClick()
+  }}
+/>`,
+    },
+    // This is invalid, but we can fix it anyway
+    {
+      code: `<ActionList.Item aria-label="Edit item 1" onClick />`,
+      errors: [{messageId: 'prefer-action-list-item-onselect'}],
+      output: `<ActionList.Item aria-label="Edit item 1" onSelect />`,
+    },
+  ],
+})
diff --git a/src/rules/prefer-action-list-item-onselect.js b/src/rules/prefer-action-list-item-onselect.js
new file mode 100644
index 0000000..85239ed
--- /dev/null
+++ b/src/rules/prefer-action-list-item-onselect.js
@@ -0,0 +1,67 @@
+// @ts-check
+
+const messages = {
+  'prefer-action-list-item-onselect': `Use the 'onSelect' event handler instead of 'onClick' for ActionList.Item components, so that it is accessible by keyboard and mouse.`,
+}
+
+/** @type {import('@typescript-eslint/utils/ts-eslint').RuleModule<keyof typeof messages>} */
+module.exports = {
+  meta: {
+    docs: {
+      description:
+        'To do something when an `ActionList.Item` is selected, you should use the `onSelect` event handler instead of `onClick`, because it handles both keyboard and mouse events. Otherwise, it will only be accessible by mouse.',
+      recommended: true,
+    },
+    messages,
+    type: 'problem',
+    schema: [],
+    fixable: 'code',
+  },
+  defaultOptions: [],
+  create(context) {
+    return {
+      JSXElement(node) {
+        // Only check components that have the name `ActionList.Item`. We don't check if this comes from Primer
+        // because the chance of conflict here is very low
+        const isActionListItem =
+          node.openingElement.name.type === 'JSXMemberExpression' &&
+          node.openingElement.name.object.type === 'JSXIdentifier' &&
+          node.openingElement.name.object.name === 'ActionList' &&
+          node.openingElement.name.property.name === 'Item'
+        if (!isActionListItem) return
+
+        const attributes = node.openingElement.attributes
+        const onClickAttribute = attributes.find(attr => attr.type === 'JSXAttribute' && attr.name.name === 'onClick')
+        const onSelectAttribute = attributes.find(attr => attr.type === 'JSXAttribute' && attr.name.name === 'onSelect')
+
+        const keyboardHandlers = ['onKeyDown', 'onKeyUp']
+        const keyboardAttributes = attributes.filter(
+          attr =>
+            attr.type === 'JSXAttribute' &&
+            (typeof attr.name.name === 'string'
+              ? keyboardHandlers.includes(attr.name.name)
+              : keyboardHandlers.includes(attr.name.name.name)),
+        )
+
+        // If the component has `onSelect`, then it's already using the correct event
+        if (onSelectAttribute) return
+        // If there is no `onClick` attribute, then we should also be fine
+        if (!onClickAttribute) return
+        // If there is an onClick attribute as well as keyboard handlers, we will assume it is handled correctly
+        if (onClickAttribute && keyboardAttributes.length > 0) return
+
+        context.report({
+          node: onClickAttribute,
+          messageId: 'prefer-action-list-item-onselect',
+          fix: fixer => {
+            // Replace `onClick` with `onSelect`
+            if (onClickAttribute.type === 'JSXAttribute') {
+              return fixer.replaceText(onClickAttribute.name, 'onSelect')
+            }
+            return null
+          },
+        })
+      },
+    }
+  },
+}