eslint-plugin-primer-react 4.0.0-rc.4ff148f → 4.0.0-rc.8a65ea9

package/CHANGELOG.md

@@ -6,6 +6,8 @@
 
 - [#51](https://github.com/primer/eslint-plugin-primer-react/pull/51) [`a65aa32`](https://github.com/primer/eslint-plugin-primer-react/commit/a65aa32c612c7fe952ec47bb3d926cf8adae9fab) Thanks [@broccolinisoup](https://github.com/broccolinisoup)! - Add `a11y-tooltip-interactive-trigger`
 
+* [#66](https://github.com/primer/eslint-plugin-primer-react/pull/66) [`d1df609`](https://github.com/primer/eslint-plugin-primer-react/commit/d1df609b260505ee9dea1740bc96a3187355d727) Thanks [@TylerJDev](https://github.com/TylerJDev)! - Add `a11y-explicit-heading` rule
+
 ## 3.0.0
 
 ### Major Changes

package/docs/rules/explicit-heading.md

@@ -0,0 +1,37 @@
+## Require explicit heading level on `<Heading>` component
+
+The `Heading` component does not require you to use `as` to specify the heading level, as it will default to an `h2` if one isn't specified. This may lead to inaccessible usage if the default is out of order in the existing heading hierarchy. 
+
+## Rule Details
+
+This rule enforces using `as` on the `<Heading>` component to specify a heading level (`h1`-`h6`). In addition, it enforces `as` usage to only be used for headings.
+
+👎 Examples of **incorrect** code for this rule
+
+```jsx
+import {Heading} from '@primer/react'
+
+<Heading>Heading without explicit heading level</Heading>
+```
+
+`as` must only be for headings (`h1`-`h6`)
+
+```jsx
+import {Heading} from '@primer/react'
+
+<Heading as="span">Heading component used as "span"</Heading>
+```
+
+👍 Examples of **correct** code for this rule:
+
+```jsx
+import {Heading} from '@primer/react';
+
+<Heading as="h2">Heading level 2</Heading>
+```
+
+## Options
+
+- `skipImportCheck` (default: `false`)
+
+  By default, the `a11y-explicit-heading` rule will only check for `<Heading>` components imported directly from `@primer/react`. You can disable this behavior by setting `skipImportCheck` to `true`.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "eslint-plugin-primer-react",
-  "version": "1.0.1",
+  "version": "3.0.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "eslint-plugin-primer-react",
-      "version": "1.0.1",
+      "version": "3.0.0",
       "license": "MIT",
       "dependencies": {
         "@styled-system/props": "^5.1.5",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-primer-react",
-  "version": "4.0.0-rc.4ff148f",
+  "version": "4.0.0-rc.8a65ea9",
   "description": "ESLint rules for Primer React",
   "main": "src/index.js",
   "scripts": {

package/src/configs/recommended.js

@@ -11,7 +11,8 @@ module.exports = {
     'primer-react/direct-slot-children': 'error',
     'primer-react/no-deprecated-colors': 'warn',
     'primer-react/no-system-props': 'warn',
-    'primer-react/a11y-tooltip-interactive-trigger': 'error'
+    'primer-react/a11y-tooltip-interactive-trigger': 'error',
+    'primer-react/a11y-explicit-heading': 'error'
   },
   settings: {
     github: {

package/src/index.js

@@ -3,7 +3,8 @@ module.exports = {
     'direct-slot-children': require('./rules/direct-slot-children'),
     'no-deprecated-colors': require('./rules/no-deprecated-colors'),
     'no-system-props': require('./rules/no-system-props'),
-    'a11y-tooltip-interactive-trigger': require('./rules/a11y-tooltip-interactive-trigger')
+    '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,41 @@
+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>
+  `,
+],
+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/a11y-explicit-heading.js

@@ -0,0 +1,60 @@
+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 => {
+  const elemAs = isUsingAsProp(elem)
+
+  if (!elemAs) return 'nonExplicitHeadingLevel'
+  if (!isValidAsUsage(elemAs.value)) return 'invalidAsValue'
+
+  return false
+}
+
+module.exports = {
+  meta: {
+    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
+            })
+          }
+        }
+      }
+    }
+  }
+}