From eb8024cadc6d9b313f019fef14953ba0977a3ee7 Mon Sep 17 00:00:00 2001
From: Kendall Gassner <kendallgassner@github.com>
Date: Tue, 11 Jul 2023 16:28:59 +0000
Subject: [PATCH 1/5] Create rule: a11y-no-title-attribute

---
 README.md                                     |  1 +
 docs/rules/a11y-no-title-attribute.md         |  7 +++++
 lib/index.js                                  |  1 +
 lib/rules/a11y-no-title-attribute.js          | 30 +++++++++++++++++++
 ...-no-visually-hidden-interactive-element.js |  1 -
 tests/a11y-no-title-attribute.js              | 28 +++++++++++++++++
 6 files changed, 67 insertions(+), 1 deletion(-)
 create mode 100644 docs/rules/a11y-no-title-attribute.md
 create mode 100644 lib/rules/a11y-no-title-attribute.js
 create mode 100644 tests/a11y-no-title-attribute.js

diff --git a/README.md b/README.md
index 67bdfb84..4449cf81 100644
--- a/README.md
+++ b/README.md
@@ -86,6 +86,7 @@ This config will be interpreted in the following way:
 | :------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | :- | :- | :- |
 | [a11y-aria-label-is-well-formatted](docs/rules/a11y-aria-label-is-well-formatted.md)                     | [aria-label] text should be formatted as you would visual text.                                                          | ⚛️ |    |    |
 | [a11y-no-generic-link-text](docs/rules/a11y-no-generic-link-text.md)                                     | disallow generic link text                                                                                               |    |    | ❌  |
+| [a11y-no-title-attribute](docs/rules/a11y-no-title-attribute.md)                                         | Guards against developers using the title attribute                                                                      |    |    |    |
 | [a11y-no-visually-hidden-interactive-element](docs/rules/a11y-no-visually-hidden-interactive-element.md) | Ensures that interactive elements are not visually hidden                                                                | ⚛️ |    |    |
 | [array-foreach](docs/rules/array-foreach.md)                                                             | enforce `for..of` loops over `Array.forEach`                                                                             | ✅  |    |    |
 | [async-currenttarget](docs/rules/async-currenttarget.md)                                                 | disallow `event.currentTarget` calls inside of async functions                                                           | 🔍 |    |    |
diff --git a/docs/rules/a11y-no-title-attribute.md b/docs/rules/a11y-no-title-attribute.md
new file mode 100644
index 00000000..1da5cecc
--- /dev/null
+++ b/docs/rules/a11y-no-title-attribute.md
@@ -0,0 +1,7 @@
+# Guards against developers using the title attribute (`github/a11y-no-title-attribute`)
+
+<!-- end auto-generated rule header -->
+
+## Rule Details
+
+## Version
diff --git a/lib/index.js b/lib/index.js
index e3bd98a5..40f79c0e 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -2,6 +2,7 @@ module.exports = {
   rules: {
     'a11y-no-visually-hidden-interactive-element': require('./rules/a11y-no-visually-hidden-interactive-element'),
     'a11y-no-generic-link-text': require('./rules/a11y-no-generic-link-text'),
+    'a11y-no-title-attribute': require('./rules/a11y-no-title-attribute'),
     'a11y-aria-label-is-well-formatted': require('./rules/a11y-aria-label-is-well-formatted'),
     'array-foreach': require('./rules/array-foreach'),
     'async-currenttarget': require('./rules/async-currenttarget'),
diff --git a/lib/rules/a11y-no-title-attribute.js b/lib/rules/a11y-no-title-attribute.js
new file mode 100644
index 00000000..1c5738d5
--- /dev/null
+++ b/lib/rules/a11y-no-title-attribute.js
@@ -0,0 +1,30 @@
+const {getProp, getPropValue} = require('jsx-ast-utils')
+const {getElementType} = require('../utils/get-element-type')
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Guards against developers using the title attribute',
+      url: require('../url')(module),
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return {
+      JSXElement: node => {
+        const elementType = getElementType(context, node.openingElement)
+        if (elementType !== `iframe`) {
+          const titleProp = getPropValue(getProp(node.openingElement.attributes, `title`))
+          if (titleProp) {
+            context.report({
+              node,
+              message:
+                "The title attribute is not accessible and should never be used unless for an `<iframe>`. If you cannot convey the information in another way, replace the title attribute with an accessible tooltip like, Primer React's Tooltip.",
+            })
+          }
+        }
+      },
+    }
+  },
+}
diff --git a/lib/rules/a11y-no-visually-hidden-interactive-element.js b/lib/rules/a11y-no-visually-hidden-interactive-element.js
index bb2c1c42..eed51ec3 100644
--- a/lib/rules/a11y-no-visually-hidden-interactive-element.js
+++ b/lib/rules/a11y-no-visually-hidden-interactive-element.js
@@ -79,7 +79,6 @@ module.exports = {
             message:
               'Avoid visually hidding interactive elements. Visually hiding interactive elements can be confusing to sighted keyboard users as it appears their focus has been lost when they navigate to the hidden element.',
           })
-          return
         }
       },
     }
diff --git a/tests/a11y-no-title-attribute.js b/tests/a11y-no-title-attribute.js
new file mode 100644
index 00000000..40924bd2
--- /dev/null
+++ b/tests/a11y-no-title-attribute.js
@@ -0,0 +1,28 @@
+const rule = require('../lib/rules/a11y-no-title-attribute')
+const RuleTester = require('eslint').RuleTester
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+})
+
+const errorMessage =
+  "The title attribute is not accessible and should never be used unless for an `<iframe>`. If you cannot convey the information in another way, replace the title attribute with an accessible tooltip like, Primer React's Tooltip."
+
+ruleTester.run('a11y-no-title-attribute', rule, {
+  valid: [
+    {code: '<button>Submit</button>'},
+    {code: '<iframe title="an allowed title">GitHub</iframe>'},
+    {code: '<span>some information</span>'},
+    {code: '<a href="github.com">GitHub</a>'},
+  ],
+  invalid: [
+    {code: '<a title="some title" href="github.com">GitHub</a>', errors: [{message: errorMessage}]},
+    {code: '<span><button title="some title">submit</button></span>', errors: [{message: errorMessage}]},
+  ],
+})

From b35851510864ec03c9836da58f53742eda196030 Mon Sep 17 00:00:00 2001
From: Kendall Gassner <kendallgassner@github.com>
Date: Tue, 11 Jul 2023 16:35:56 +0000
Subject: [PATCH 2/5] Add tests that check various component mappings

---
 tests/a11y-no-title-attribute.js | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/tests/a11y-no-title-attribute.js b/tests/a11y-no-title-attribute.js
index 40924bd2..1022dbae 100644
--- a/tests/a11y-no-title-attribute.js
+++ b/tests/a11y-no-title-attribute.js
@@ -20,9 +20,41 @@ ruleTester.run('a11y-no-title-attribute', rule, {
     {code: '<iframe title="an allowed title">GitHub</iframe>'},
     {code: '<span>some information</span>'},
     {code: '<a href="github.com">GitHub</a>'},
+    {
+      code: '<Component title="some title">Submit</Component>',
+      settings: {
+        github: {
+          components: {
+            Component: 'iframe',
+          },
+        },
+      },
+    },
   ],
   invalid: [
     {code: '<a title="some title" href="github.com">GitHub</a>', errors: [{message: errorMessage}]},
     {code: '<span><button title="some title">submit</button></span>', errors: [{message: errorMessage}]},
+    {
+      code: '<Link title="some title">Submit</Link>',
+      errors: [{message: errorMessage}],
+      settings: {
+        github: {
+          components: {
+            Link: 'a',
+          },
+        },
+      },
+    },
+    {
+      code: '<Component as="a" title="some title">Submit</Component>',
+      errors: [{message: errorMessage}],
+      settings: {
+        github: {
+          components: {
+            Component: 'iframe',
+          },
+        },
+      },
+    },
   ],
 })

From 2941475347ada9827e07ce772a091270a8b05920 Mon Sep 17 00:00:00 2001
From: Kendall Gassner <kendallgassner@github.com>
Date: Tue, 11 Jul 2023 16:36:47 +0000
Subject: [PATCH 3/5] Add rule to react config

---
 lib/configs/react.js | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lib/configs/react.js b/lib/configs/react.js
index 63021526..77a9b57a 100644
--- a/lib/configs/react.js
+++ b/lib/configs/react.js
@@ -11,6 +11,7 @@ module.exports = {
     'jsx-a11y/role-supports-aria-props': 'off', // Override with github/role-supports-aria-props until https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/issues/910 is resolved
     'github/a11y-aria-label-is-well-formatted': 'error',
     'github/a11y-no-visually-hidden-interactive-element': 'error',
+    'github/a11y-no-title-attribute': 'error',
     'github/role-supports-aria-props': 'error',
     'jsx-a11y/no-aria-hidden-on-focusable': 'error',
     'jsx-a11y/no-autofocus': 'off',

From 92f656d656576bc444fb049937c9b66a06e174fb Mon Sep 17 00:00:00 2001
From: Kendall Gassner <kendallgassner@github.com>
Date: Tue, 11 Jul 2023 16:55:36 +0000
Subject: [PATCH 4/5] better docs

---
 docs/rules/a11y-no-title-attribute.md | 36 +++++++++++++++++++++++++++
 lib/rules/a11y-no-title-attribute.js  |  3 +--
 tests/a11y-no-title-attribute.js      |  3 +--
 3 files changed, 38 insertions(+), 4 deletions(-)

diff --git a/docs/rules/a11y-no-title-attribute.md b/docs/rules/a11y-no-title-attribute.md
index 1da5cecc..b63774ca 100644
--- a/docs/rules/a11y-no-title-attribute.md
+++ b/docs/rules/a11y-no-title-attribute.md
@@ -2,6 +2,42 @@
 
 <!-- end auto-generated rule header -->
 
+The title attribute is strongly discouraged. The only exception is on an `<iframe>` element. It is hardly useful and cannot be accessed by multiple groups of users including keyboard-only users and mobile users.
+
+The `title` attribute is commonly set on links, matching the link text. This is redundant and unnecessary so it can be simply be removed.
+
+If you are considering the `title` attribute to provide supplementary description, consider whether the text in question can be persisted in the design. Alternatively, if it's important to display supplementary text that is hidden by default, consider using an accessible tooltip implementation that uses the aria-labelledby or aria-describedby semantics. Even so, proceed with caution: tooltips should only be used on interactive elements like links or buttons. See [Tooltip alternatives](https://primer.style/design/guides/accessibility/tooltip-alternatives) for more accessible alternatives.
+
+### Should I use the title attribute to provide an accessible name for an <svg>?
+
+Use a <title> element instead of the title attribute, or an aria-label.
+
 ## Rule Details
 
+👎 Examples of **incorrect** code for this rule:
+
+```jsx
+<a src="https://www.github.com" title="A home for all developers">
+  GitHub
+</a>
+```
+
+```jsx
+<a href="/" title="github.com">
+  GitHub
+</a>
+```
+
+```jsx
+<span src="https://www.github.com" title="supercalifragilisticexpialidocious">
+  supercali...
+</span>
+```
+
+👍 Examples of **correct** code for this rule:
+
+```jsx
+<iframe src="https://www.github.com" title="Github"></iframe>
+```
+
 ## Version
diff --git a/lib/rules/a11y-no-title-attribute.js b/lib/rules/a11y-no-title-attribute.js
index 1c5738d5..8e4e9f2d 100644
--- a/lib/rules/a11y-no-title-attribute.js
+++ b/lib/rules/a11y-no-title-attribute.js
@@ -19,8 +19,7 @@ module.exports = {
           if (titleProp) {
             context.report({
               node,
-              message:
-                "The title attribute is not accessible and should never be used unless for an `<iframe>`. If you cannot convey the information in another way, replace the title attribute with an accessible tooltip like, Primer React's Tooltip.",
+              message: 'The title attribute is not accessible and should never be used unless for an `<iframe>`.',
             })
           }
         }
diff --git a/tests/a11y-no-title-attribute.js b/tests/a11y-no-title-attribute.js
index 1022dbae..90cc1247 100644
--- a/tests/a11y-no-title-attribute.js
+++ b/tests/a11y-no-title-attribute.js
@@ -11,8 +11,7 @@ const ruleTester = new RuleTester({
   },
 })
 
-const errorMessage =
-  "The title attribute is not accessible and should never be used unless for an `<iframe>`. If you cannot convey the information in another way, replace the title attribute with an accessible tooltip like, Primer React's Tooltip."
+const errorMessage = 'The title attribute is not accessible and should never be used unless for an `<iframe>`.'
 
 ruleTester.run('a11y-no-title-attribute', rule, {
   valid: [

From 35ef90ca38e60caea2b96fcdbfc7c16166290948 Mon Sep 17 00:00:00 2001
From: Kendall Gassner <kendallgassner@github.com>
Date: Tue, 11 Jul 2023 20:54:24 +0000
Subject: [PATCH 5/5] clean

---
 lib/rules/a11y-no-title-attribute.js          | 39 ++++++++++++++++++-
 ...-no-visually-hidden-interactive-element.js |  4 +-
 lib/utils/get-element-type.js                 |  4 +-
 tests/a11y-no-title-attribute.js              | 10 ++---
 4 files changed, 47 insertions(+), 10 deletions(-)

diff --git a/lib/rules/a11y-no-title-attribute.js b/lib/rules/a11y-no-title-attribute.js
index 8e4e9f2d..83d61719 100644
--- a/lib/rules/a11y-no-title-attribute.js
+++ b/lib/rules/a11y-no-title-attribute.js
@@ -1,6 +1,43 @@
 const {getProp, getPropValue} = require('jsx-ast-utils')
 const {getElementType} = require('../utils/get-element-type')
 
+const SEMANTIC_ELEMENTS = [
+  'a',
+  'button',
+  'summary',
+  'select',
+  'option',
+  'textarea',
+  'input',
+  'span',
+  'div',
+  'p',
+  'h1',
+  'h2',
+  'h3',
+  'h4',
+  'h5',
+  'h6',
+  'details',
+  'summary',
+  'dialog',
+  'tr',
+  'th',
+  'td',
+  'label',
+]
+
+const ifSemanticElement = (context, node) => {
+  const elementType = getElementType(context, node.openingElement, true)
+
+  for (const semanticElement of SEMANTIC_ELEMENTS) {
+    if (elementType === semanticElement) {
+      return true
+    }
+  }
+  return false
+}
+
 module.exports = {
   meta: {
     docs: {
@@ -14,7 +51,7 @@ module.exports = {
     return {
       JSXElement: node => {
         const elementType = getElementType(context, node.openingElement)
-        if (elementType !== `iframe`) {
+        if (elementType !== `iframe` && ifSemanticElement(context, node)) {
           const titleProp = getPropValue(getProp(node.openingElement.attributes, `title`))
           if (titleProp) {
             context.report({
diff --git a/lib/rules/a11y-no-visually-hidden-interactive-element.js b/lib/rules/a11y-no-visually-hidden-interactive-element.js
index 1f59e84c..3c12812d 100644
--- a/lib/rules/a11y-no-visually-hidden-interactive-element.js
+++ b/lib/rules/a11y-no-visually-hidden-interactive-element.js
@@ -15,12 +15,12 @@ const schema = generateObjSchema({
  * because a visually hidden input field might cause a false positive.
  * (e.g. fileUpload https://github.com/primer/react/pull/3492)
  */
-const INTERACTIVELEMENTS = ['a', 'button', 'summary', 'select', 'option', 'textarea']
+const INTERACTIVE_ELEMENTS = ['a', 'button', 'summary', 'select', 'option', 'textarea']
 
 const checkIfInteractiveElement = (context, node) => {
   const elementType = getElementType(context, node.openingElement)
 
-  for (const interactiveElement of INTERACTIVELEMENTS) {
+  for (const interactiveElement of INTERACTIVE_ELEMENTS) {
     if (elementType === interactiveElement) {
       return true
     }
diff --git a/lib/utils/get-element-type.js b/lib/utils/get-element-type.js
index d53b893d..2d2a531b 100644
--- a/lib/utils/get-element-type.js
+++ b/lib/utils/get-element-type.js
@@ -7,7 +7,7 @@ If a prop determines the type, it can be specified with `props`.
 
 For now, we only support the mapping of one prop type to an element type, rather than combinations of props.
 */
-function getElementType(context, node) {
+function getElementType(context, node, ignoreMap = false) {
   const {settings} = context
 
   // check if the node contains a polymorphic prop
@@ -15,7 +15,7 @@ function getElementType(context, node) {
   const rawElement = getPropValue(getProp(node.attributes, polymorphicPropName)) ?? elementType(node)
 
   // if a component configuration does not exists, return the raw element
-  if (!settings?.github?.components?.[rawElement]) return rawElement
+  if (ignoreMap || !settings?.github?.components?.[rawElement]) return rawElement
 
   const defaultComponent = settings.github.components[rawElement]
 
diff --git a/tests/a11y-no-title-attribute.js b/tests/a11y-no-title-attribute.js
index 90cc1247..3f620ea8 100644
--- a/tests/a11y-no-title-attribute.js
+++ b/tests/a11y-no-title-attribute.js
@@ -29,13 +29,9 @@ ruleTester.run('a11y-no-title-attribute', rule, {
         },
       },
     },
-  ],
-  invalid: [
-    {code: '<a title="some title" href="github.com">GitHub</a>', errors: [{message: errorMessage}]},
-    {code: '<span><button title="some title">submit</button></span>', errors: [{message: errorMessage}]},
     {
+      // Note: we are only checking semantic elements. We cannot make assumptions about how a React Components is using the title prop.
       code: '<Link title="some title">Submit</Link>',
-      errors: [{message: errorMessage}],
       settings: {
         github: {
           components: {
@@ -44,6 +40,10 @@ ruleTester.run('a11y-no-title-attribute', rule, {
         },
       },
     },
+  ],
+  invalid: [
+    {code: '<a title="some title" href="github.com">GitHub</a>', errors: [{message: errorMessage}]},
+    {code: '<span><button title="some title">submit</button></span>', errors: [{message: errorMessage}]},
     {
       code: '<Component as="a" title="some title">Submit</Component>',
       errors: [{message: errorMessage}],