eslint-plugin-primer-react 3.0.0 → 4.0.0-rc.2ea2bf7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-primer-react",
-  "version": "3.0.0",
+  "version": "4.0.0-rc.2ea2bf7",
   "description": "ESLint rules for Primer React",
   "main": "src/index.js",
   "scripts": {
@@ -24,7 +24,7 @@
     "@changesets/changelog-github": "^0.4.0",
     "@changesets/cli": "^2.16.0",
     "@github/prettier-config": "0.0.4",
-    "@primer/primitives": "^5.1.0",
+    "@primer/primitives": "^7.11.14",
     "eslint": "^8.0.1",
     "jest": "^27.0.6"
   },
@@ -35,8 +35,8 @@
   "prettier": "@github/prettier-config",
   "dependencies": {
     "@styled-system/props": "^5.1.5",
-    "eslint-plugin-github": "^4.3.7",
-    "eslint-plugin-jsx-a11y": "^6.6.1",
+    "eslint-plugin-github": "^4.9.2",
+    "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-traverse": "^1.0.0",
     "lodash": "^4.17.21",
     "styled-system": "^5.1.5"

package/src/configs/components.js

@@ -0,0 +1,26 @@
+const { flattenComponents } = require('../utils/flatten-components');
+
+const components = flattenComponents({
+    Button: 'button',
+    IconButton: 'button',
+    Link: 'a',
+    Spinner: 'svg',
+    ToggleSwitch: 'button',
+    Radio: 'input',
+    Checkbox: 'input',
+    Text: 'span',
+    TextInput: {
+        Action: 'button',
+        self: 'input',
+    }, 
+    Select: {
+        Option: 'option', 
+        self: 'select',
+     },
+    TabNav: {
+        Link: 'a',
+        self: 'nav',
+    },
+})
+
+module.exports = components;

package/src/configs/recommended.js

@@ -1,3 +1,5 @@
+const components = require('./components');
+
 module.exports = {
   parserOptions: {
     sourceType: 'module',
@@ -10,20 +12,16 @@ module.exports = {
   rules: {
     'primer-react/direct-slot-children': 'error',
     'primer-react/no-deprecated-colors': 'warn',
-    'primer-react/no-system-props': 'warn'
+    'primer-react/no-system-props': 'warn',
+    'primer-react/a11y-tooltip-interactive-trigger': 'error',
+    'primer-react/a11y-explicit-heading': 'error'
   },
   settings: {
     github: {
-      components: {
-        Link: {props: {as: {undefined: 'a', a: 'a', button: 'button'}}},
-        Button: {default: 'button'}
-      }
+      components: components
     },
     'jsx-a11y': {
-      components: {
-        Button: 'button',
-        IconButton: 'button'
-      }
+      components: components
     }
   }
 }

package/src/index.js

@@ -2,7 +2,9 @@ module.exports = {
   rules: {
     'direct-slot-children': require('./rules/direct-slot-children'),
     'no-deprecated-colors': require('./rules/no-deprecated-colors'),
-    'no-system-props': require('./rules/no-system-props')
+    'no-system-props': require('./rules/no-system-props'),
+    'a11y-tooltip-interactive-trigger': require('./rules/a11y-tooltip-interactive-trigger'),
+    'a11y-explicit-heading': require('./rules/a11y-explicit-heading')
   },
   configs: {
     recommended: require('./configs/recommended')

package/src/rules/__tests__/a11y-explicit-heading.test.js

@@ -0,0 +1,54 @@
+const rule = require('../a11y-explicit-heading')
+const {RuleTester} = require('eslint')
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true
+    }
+  }
+})
+
+ruleTester.run('a11y-explicit-heading', rule, {
+  valid: [
+  `import {Heading} from '@primer/react';
+  <Heading as="h1">Heading level 1</Heading>
+  `,
+  `import {Heading} from '@primer/react';
+  <Heading as="h2">Heading level 2</Heading>
+  `,
+  `import {Heading} from '@primer/react';
+  <Heading as="H3">Heading level 3</Heading>
+  `,
+  `import {Heading} from '@primer/react';
+  const args = {};
+  <Heading {...args}>A heading with spread props</Heading>
+  `,
+  `import {Heading} from '@primer/react';
+  const as = 'h3';
+  <Heading as={as}>Heading as passed prop</Heading>
+  `,
+  `import {Heading} from '@primer/react';
+  const args = {};
+  <Heading as="h2" {...args}>Heading level 2</Heading>
+  `,
+  
+],
+invalid: [    
+  {
+    code: 
+    `import {Heading} from '@primer/react';
+    <Heading>Heading without "as"</Heading>`,
+    errors: [{ messageId: 'nonExplicitHeadingLevel' }]
+  },
+  {
+    code: 
+    `import {Heading} from '@primer/react';
+    <Heading as="span">Heading component used as "span"</Heading>
+    `,
+    errors: [{ messageId: 'invalidAsValue' }]
+  },
+]
+})

package/src/rules/__tests__/a11y-tooltip-interactive-trigger.test.js

@@ -0,0 +1,167 @@
+const rule = require('../a11y-tooltip-interactive-trigger')
+const {RuleTester} = require('eslint')
+
+const ruleTester = new RuleTester({
+  parserOptions: {
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+    ecmaFeatures: {
+      jsx: true
+    }
+  }
+})
+
+ruleTester.run('non-interactive-tooltip-trigger', rule, {
+  valid: [
+    `import {Tooltip, Button} from '@primer/react';
+    <Tooltip aria-label="Filter vegetarian options" direction="e">
+      <Button>🥦</Button>
+    </Tooltip>`,
+
+    `import {Tooltip, Button} from '@primer/react';
+    <Tooltip aria-label="Supplementary text" direction="e">
+      <Button>Save</Button>
+    </Tooltip>`,
+
+    `import {Tooltip, IconButton} from '@primer/react';
+    import {SearchIcon} from '@primer/octicons-react';
+    <Tooltip aria-label="Supplementary text" direction="e">
+      <IconButton icon={SearchIcon} aria-label="Search" />
+    </Tooltip>`,
+
+    `import {Tooltip, Button} from '@primer/react';
+    <Tooltip aria-label="Supplementary text" direction="e">
+      <div>
+        <Button>Save</Button>
+      </div>
+    </Tooltip>`,
+
+    `import {Tooltip, Button} from '@primer/react';
+    <Tooltip aria-label="Supplementary text" direction="e">
+      <div>
+        <a href="https://gthub.com">Save</a>
+      </div>
+    </Tooltip>`,
+
+    `import {Tooltip} from '@primer/react';
+    <Tooltip aria-label="Supplementary text" direction="e">
+      <a href="https://github.com">see commit message</a>
+    </Tooltip>`,
+
+    `import {Tooltip, Link} from '@primer/react';
+    <Tooltip aria-label="Supplementary text" direction="e">
+      <Link href="https://github.com">Link</Link>
+    </Tooltip>`
+  ],
+  invalid: [
+    {
+      code: `import {Tooltip} from '@primer/react';<Tooltip type="description" text="supportive text" direction="e"><button>button1</button><button>button2</button></Tooltip>
+      `,
+      errors: [
+        {
+          messageId: 'singleChild'
+        }
+      ]
+    },
+    {
+      code: `
+      import {Tooltip} from '@primer/react';
+      <Tooltip aria-label="Filter vegetarian options" direction="e">
+        <span>non interactive element</span>
+      </Tooltip>
+      `,
+      errors: [
+        {
+          messageId: 'nonInteractiveTrigger'
+        }
+      ]
+    },
+    {
+      code: `
+      import {Tooltip, Button} from '@primer/react';
+      <Tooltip aria-label="Supplementary text" direction="e">
+        <h1>Save</h1>
+      </Tooltip>`,
+      errors: [
+        {
+          messageId: 'nonInteractiveTrigger'
+        }
+      ]
+    },
+    {
+      code: `
+      import {Tooltip} from '@primer/react';
+      <Tooltip aria-label="Supplementary text" direction="e">
+        <a>see commit message</a>
+      </Tooltip>`,
+      errors: [
+        {
+          messageId: 'anchorTagWithoutHref'
+        }
+      ]
+    },
+    {
+      code: `
+      import {Tooltip, Link} from '@primer/react';
+      <Tooltip aria-label="Supplementary text" direction="e">
+        <Link>see commit message</Link>
+      </Tooltip>`,
+      errors: [
+        {
+          messageId: 'anchorTagWithoutHref'
+        }
+      ]
+    },
+    {
+      code: `
+      import {Tooltip} from '@primer/react';
+      <Tooltip aria-label="Supplementary text" direction="e">
+        <input type="hidden" />
+      </Tooltip>`,
+      errors: [
+        {
+          messageId: 'hiddenInput'
+        }
+      ]
+    },
+    {
+      code: `
+      import {Tooltip, TextInput} from '@primer/react';
+      <Tooltip aria-label="Supplementary text" direction="e">
+        <TextInput type="hidden" aria-label="Zipcode" name="zipcode" placeholder="Zipcode" autoComplete="postal-code" />
+      </Tooltip>`,
+      errors: [
+        {
+          messageId: 'hiddenInput'
+        }
+      ]
+    },
+    {
+      code: `
+      import {Tooltip, Button} from '@primer/react';
+      <Tooltip aria-label="Supplementary text" direction="e">
+        <header>
+          <span>Save</span>
+        </header>
+      </Tooltip>`,
+      errors: [
+        {
+          messageId: 'nonInteractiveTrigger'
+        }
+      ]
+    },
+    {
+      code: `import {Tooltip, Button} from '@primer/react';
+      <Tooltip aria-label="Supplementary text" direction="e">
+        <h1>
+          <a>Save</a>
+        </h1>
+      </Tooltip>`,
+      errors: [
+        {
+          messageId: 'anchorTagWithoutHref'
+        }
+      ]
+    }
+  ]
+})

package/src/rules/a11y-explicit-heading.js

@@ -0,0 +1,66 @@
+const {isPrimerComponent} = require('../utils/is-primer-component')
+const {getJSXOpeningElementName} = require('../utils/get-jsx-opening-element-name')
+const {getJSXOpeningElementAttribute} = require('../utils/get-jsx-opening-element-attribute')
+
+const validHeadings = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6']
+
+const isHeadingComponent = elem => getJSXOpeningElementName(elem) === 'Heading'
+const isUsingAsProp = elem => {
+  const componentAs = getJSXOpeningElementAttribute(elem, 'as')
+
+  if (!componentAs) return
+
+  return componentAs.value
+}
+
+const isValidAsUsage = value => validHeadings.includes(value.toLowerCase())
+const isInvalid = elem => {
+  if (elem.attributes.length === 1 && elem.attributes[0].type === 'JSXSpreadAttribute') return;
+
+  const elemAs = isUsingAsProp(elem)
+
+  if (!elemAs) return 'nonExplicitHeadingLevel'
+  if (elemAs.value && !isValidAsUsage(elemAs.value)) return 'invalidAsValue'
+
+  return false
+}
+
+module.exports = {
+  meta: {
+    docs: {
+      description: 'Heading component must have explicit heading level, and specific `as` usage.',
+      url: require('../url')(module),
+    },
+    schema: [
+      {
+        properties: {
+          skipImportCheck: {
+            type: 'boolean'
+          }
+        }
+      }
+    ],
+    messages: {
+      nonExplicitHeadingLevel: 'Heading must have an explicit heading level applied through the `as` prop.',
+      invalidAsValue: 'Usage of `as` must only be used for heading elements (h1-h6).'
+    }
+  },
+  create: function(context) {
+    return {
+      JSXOpeningElement(jsxNode) {
+        const skipImportCheck = context.options[0] ? context.options[0].skipImportCheck : false
+
+        if ((skipImportCheck || isPrimerComponent(jsxNode.name, context.getScope(jsxNode))) && isHeadingComponent(jsxNode)) {
+          const error = isInvalid(jsxNode)
+
+          if (error) {
+            context.report({
+              node: jsxNode,
+              messageId: error
+            })
+          }
+        }
+      }
+    }
+  }
+}

package/src/rules/a11y-tooltip-interactive-trigger.js

@@ -0,0 +1,179 @@
+const {isPrimerComponent} = require('../utils/is-primer-component')
+const {getJSXOpeningElementName} = require('../utils/get-jsx-opening-element-name')
+const {getJSXOpeningElementAttribute} = require('../utils/get-jsx-opening-element-attribute')
+
+const isInteractive = child => {
+  const childName = getJSXOpeningElementName(child.openingElement)
+  return ['button', 'summary', 'select', 'textarea', 'a', 'input', 'link', 'iconbutton', 'textinput'].includes(
+    childName.toLowerCase()
+  )
+}
+
+const isAnchorTag = el => {
+  return (
+    getJSXOpeningElementName(el.openingElement) === 'a' ||
+    getJSXOpeningElementName(el.openingElement).toLowerCase() === 'link'
+  )
+}
+
+const isInteractiveAnchor = child => {
+  const hasHref = getJSXOpeningElementAttribute(child.openingElement, 'href')
+  if (!hasHref) return false
+  const href = getJSXOpeningElementAttribute(child.openingElement, 'href').value.value
+  const isAnchorInteractive = typeof href === 'string' && href !== ''
+  return isAnchorInteractive
+}
+
+const isInputTag = el => {
+  return (
+    getJSXOpeningElementName(el.openingElement) === 'input' ||
+    getJSXOpeningElementName(el.openingElement).toLowerCase() === 'textinput'
+  )
+}
+
+const isInteractiveInput = child => {
+  const hasHiddenType =
+    getJSXOpeningElementAttribute(child.openingElement, 'type') &&
+    getJSXOpeningElementAttribute(child.openingElement, 'type').value.value === 'hidden'
+  return !hasHiddenType
+}
+
+const isOtherThanAnchorOrInput = el => {
+  return !isAnchorTag(el) && !isInputTag(el)
+}
+
+const getAllChildren = node => {
+  if (Array.isArray(node.children)) {
+    return node.children
+      .filter(child => {
+        return child.type === 'JSXElement'
+      })
+      .flatMap(child => {
+        return [child, ...getAllChildren(child)]
+      })
+  }
+  return []
+}
+
+const checks = [
+  {
+    id: 'anchorTagWithoutHref',
+    filter: jsxElement => isAnchorTag(jsxElement),
+    check: isInteractiveAnchor
+  },
+  {
+    id: 'hiddenInput',
+    filter: jsxElement => isInputTag(jsxElement),
+    check: isInteractiveInput
+  },
+  {
+    id: 'nonInteractiveTrigger',
+    filter: jsxElement => isOtherThanAnchorOrInput(jsxElement),
+    check: isInteractive
+  }
+]
+
+const checkTriggerElement = jsxNode => {
+  const elements = [...getAllChildren(jsxNode)]
+  const hasInteractiveElement = elements.find(element => {
+    if (
+      getJSXOpeningElementName(element.openingElement) === 'a' ||
+      getJSXOpeningElementName(element.openingElement) === 'Link'
+    ) {
+      return isInteractiveAnchor(element)
+    }
+    if (
+      getJSXOpeningElementName(element.openingElement) === 'input' ||
+      getJSXOpeningElementName(element.openingElement) === 'TextInput'
+    ) {
+      return isInteractiveInput(element)
+    } else {
+      return isInteractive(element)
+    }
+  })
+
+  // If the tooltip has interactive elements, return.
+  if (hasInteractiveElement) return
+
+  const errors = new Set()
+
+  for (const element of elements) {
+    for (const check of checks) {
+      if (!check.filter(element)) {
+        continue
+      }
+
+      if (!check.check(element)) {
+        errors.add(check.id)
+      }
+    }
+  }
+  // check the specificity of the errors. If there are multiple errors, only return the most specific one.
+  if (errors.size > 1) {
+    if (errors.has('anchorTagWithoutHref')) {
+      errors.delete('nonInteractiveTrigger')
+    }
+    if (errors.has('hiddenInput')) {
+      errors.delete('nonInteractiveTrigger')
+    }
+  }
+
+  return errors
+}
+
+module.exports = {
+  meta: {
+    type: 'problem',
+    schema: [
+      {
+        properties: {
+          skipImportCheck: {
+            type: 'boolean'
+          }
+        }
+      }
+    ],
+    messages: {
+      nonInteractiveTrigger:
+        'The `Tooltip` component expects a single React element that contains interactive content. Consider using a `<button>` or equivalent interactive element instead.',
+      anchorTagWithoutHref:
+        'Anchor tags without an href attribute are not interactive, therefore they cannot be used as a trigger for a tooltip. Please add an href attribute or use an alternative interactive element instead',
+      hiddenInput:
+        'Hidden inputs are not interactive and cannot be used as a trigger for a tooltip. Please use an alternate input type or use a different interactive element instead',
+      singleChild: 'The `Tooltip` component expects a single React element as a child.'
+    }
+  },
+  create(context) {
+    return {
+      JSXElement(jsxNode) {
+        // If `skipImportCheck` is true, this rule will check for non-interactive element in any components (not just ones that are imported from `@primer/react`).
+        const skipImportCheck = context.options[0] ? context.options[0].skipImportCheck : false
+        const name = getJSXOpeningElementName(jsxNode.openingElement)
+        if (
+          (skipImportCheck || isPrimerComponent(jsxNode.openingElement.name, context.getScope(jsxNode))) &&
+          name === 'Tooltip' &&
+          jsxNode.children
+        ) {
+          if (jsxNode.children.filter(child => child.type === 'JSXElement').length > 1) {
+            context.report({
+              node: jsxNode,
+              messageId: 'singleChild'
+            })
+          } else {
+            // Check if the child is interactive
+            const errors = checkTriggerElement(jsxNode)
+
+            if (errors) {
+              for (const [key, value] of errors.entries()) {
+                context.report({
+                  node: jsxNode,
+                  messageId: value
+                })
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/url.js

@@ -0,0 +1,10 @@
+const {homepage, version} = require('../package.json')
+const path = require('path')
+
+module.exports = ({id}) => {
+  const url = new URL(homepage)
+  const rule = path.basename(id, '.js')
+  url.hash = ''
+  url.pathname += `/blob/v${version}/docs/rules/${rule}.md`
+  return url.toString()
+}

package/src/utils/__tests__/flatten-components.test.js

@@ -0,0 +1,62 @@
+const {flattenComponents} = require('../flatten-components')
+
+const mockComponents = function(passedObj) {
+  return {
+    Button: 'button',
+    Link: 'a',
+    Spinner: 'svg',
+    Radio: 'input',
+    TextInput: {
+      Action: 'button',
+      self: 'input'
+    },
+    ...passedObj
+  }
+}
+
+describe('getElementType', function() {
+  it('flattens passed object 1-level deep', function() {
+    const result = flattenComponents(mockComponents())
+
+    const expectedResult = {
+      Button: 'button',
+      Link: 'a',
+      Spinner: 'svg',
+      Radio: 'input',
+      TextInput: 'input',
+      'TextInput.Action': 'button'
+    }
+
+    expect(result).toEqual(expectedResult)
+  })
+
+  it('ignores objects nested deeper than 1-level', function() {
+    const result = flattenComponents(
+      mockComponents({
+        Select: {
+          Items: {
+            self: 'div'
+          },
+          Option: 'option',
+          self: 'select'
+        }
+      })
+    )
+
+    const expectedResult = {
+      Button: 'button',
+      Link: 'a',
+      Spinner: 'svg',
+      Radio: 'input',
+      TextInput: 'input',
+      'TextInput.Action': 'button',
+      'Select.Items': {
+        self: 'div'
+      },
+      Select: 'select',
+      'Select.Option': 'option'
+    }
+
+    expect(result).toEqual(expectedResult)
+  })
+})

package/src/utils/flatten-components.js

@@ -0,0 +1,17 @@
+function flattenComponents(componentObj) {
+    let result = {};
+
+    Object.keys(componentObj).forEach((key) => {
+        if (typeof componentObj[key] === 'object') {
+            const test = Object.keys(componentObj[key]).forEach((item) => {
+                result = { ...result, [`${key}${item !== 'self' ? `.${item}` : ''}`]: componentObj[key][item] };        
+            });
+        } else {
+            result = {...result, [key]: componentObj[key]}
+        }
+    });
+
+    return result;
+}
+
+exports.flattenComponents = flattenComponents

package/src/utils/get-jsx-opening-element-attribute.js

@@ -0,0 +1,10 @@
+function getJSXOpeningElementAttribute(openingEl, name) {
+  const attributes = openingEl.attributes
+  const attribute = attributes.find(attribute => {
+    return attribute.name.name === name
+  })
+
+  return attribute
+}
+
+exports.getJSXOpeningElementAttribute = getJSXOpeningElementAttribute