eslint-plugin-primer-react 5.5.0-rc.40574df → 6.0.0-rc.2964cbe

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-primer-react",
-  "version": "5.5.0-rc.40574df",
+  "version": "6.0.0-rc.2964cbe",
   "description": "ESLint rules for Primer React",
   "main": "src/index.js",
   "scripts": {
@@ -33,7 +33,9 @@
     "eslint-plugin-jsx-a11y": "^6.7.1",
     "eslint-traverse": "^1.0.0",
     "lodash": "^4.17.21",
-    "styled-system": "^5.1.5"
+    "styled-system": "^5.1.5",
+    "@typescript-eslint/utils": "7.16.0",
+    "typescript": "^5.5.3"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.0",
@@ -44,7 +46,9 @@
     "eslint-plugin-prettier": "^5.0.1",
     "jest": "^29.7.0",
     "markdownlint-cli2": "^0.13.0",
-    "markdownlint-cli2-formatter-pretty": "^0.0.6"
+    "markdownlint-cli2-formatter-pretty": "^0.0.6",
+    "@typescript-eslint/rule-tester": "7.16.0",
+    "@types/jest": "^29.5.12"
   },
   "prettier": "@github/prettier-config"
 }

package/src/configs/recommended.js

@@ -18,6 +18,8 @@ module.exports = {
     'primer-react/no-deprecated-props': 'warn',
     '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: {

package/src/index.js

@@ -11,6 +11,8 @@ module.exports = {
     'a11y-remove-disable-tooltip': require('./rules/a11y-remove-disable-tooltip'),
     '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'),

package/src/rules/__tests__/fixtures/File.tsx

@@ -0,0 +1 @@
+// https://typescript-eslint.io/packages/rule-tester/#type-aware-testing

package/src/rules/__tests__/fixtures/file.ts

@@ -0,0 +1 @@
+// https://typescript-eslint.io/packages/rule-tester/#type-aware-testing

package/src/rules/__tests__/fixtures/tsconfig.json

@@ -0,0 +1,7 @@
+// https://typescript-eslint.io/packages/rule-tester/#type-aware-testing
+{
+  "compilerOptions": {
+    "strict": true
+  },
+  "include": ["file.ts", "File.tsx"]
+}

package/src/rules/__tests__/no-unnecessary-components.test.js

@@ -0,0 +1,153 @@
+// @ts-check
+
+const {RuleTester} = require('@typescript-eslint/rule-tester')
+
+const path = require('node:path')
+const rule = require('../no-unnecessary-components')
+const {components} = require('../no-unnecessary-components')
+
+const prcImport = 'import React from "react"; import {Box, Text} from "@primer/react";'
+const brandImport = 'import React from "react"; import {Box, Text} from "@primer/brand";'
+
+/** @param {string} content */
+const jsx = content => `export const Component = () => <>${content}</>`
+
+const sxObjectDeclaration = `const props = {sx: {color: "red"}};`
+const asObjectDeclaration = `const props = {as: "table"};`
+const stringRecordDeclaration = `const props: Record<string, any> = {};`
+const testIdObjectDeclaration = `const props = {'data-testid': 'xyz'};`
+const componentDeclaration = `const OtherComponent = ({children}: {children: React.ReactNode}) => <>{children}</>;`
+const asConstDeclaration = `const as = "p";`
+
+const ruleTester = new RuleTester({
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    tsconfigRootDir: path.resolve(__dirname, 'fixtures'),
+    project: path.resolve(__dirname, 'fixtures', 'tsconfig.json'),
+  },
+  defaultFilenames: {
+    ts: 'file.ts',
+    tsx: 'File.tsx',
+  },
+})
+
+jest.retryTimes(0, {logErrorsBeforeRetry: true})
+
+const filename = 'File.tsx'
+
+ruleTester.run('unnecessary-components', rule, {
+  valid: [
+    {name: 'Unrelated JSX', code: jsx('<span>Hello World</span>'), filename},
+    ...Object.keys(components).flatMap(component => [
+      {
+        name: `Non-PRC ${component}`,
+        code: `${brandImport}${jsx(`<${component}>Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with sx prop`,
+        code: `${prcImport}${jsx(`<${component} sx={{color: "red"}}>Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with any styled-system prop`,
+        code: `${prcImport}${jsx(`<${component} flex="row">Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with spread sx prop`,
+        code: `${prcImport}${sxObjectDeclaration}${jsx(`<${component} {...props}>Hello World</${component}>`)}`,
+        filename,
+      },
+      {
+        name: `${component} with string index spread props`,
+        code: `${prcImport}${stringRecordDeclaration}${jsx(`<${component} {...props}>Hello World</${component}>`)}`,
+        filename,
+      },
+    ]),
+    {
+      name: `Text with weight prop`,
+      code: `${prcImport}${jsx(`<Text weight='medium'>Hello World</Text>`)}`,
+      filename,
+    },
+    {
+      name: `Text with size prop`,
+      code: `${prcImport}${jsx(`<Text size='small'>Hello World</Text>`)}`,
+      filename,
+    },
+  ],
+  invalid: Object.entries(components).flatMap(([component, {messageId, replacement}]) => [
+    {
+      name: `${component} without any styled-system props`,
+      code: `${prcImport}${jsx(`<${component}>Hello World</${component}>`)}`,
+      output: `${prcImport}${jsx(`<${replacement}>Hello World</${replacement}>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `Self-closing ${component} without any styled-system props`,
+      code: `${prcImport}${jsx(`<${component} />`)}`,
+      output: `${prcImport}${jsx(`<${replacement} />`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with spread props without sx`,
+      code: `${prcImport}${testIdObjectDeclaration}${jsx(`<${component} {...props}>Hello World</${component}>`)}`,
+      output: `${prcImport}${testIdObjectDeclaration}${jsx(`<${replacement} {...props}>Hello World</${replacement}>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with string element 'as' prop`,
+      code: `${prcImport}${jsx(`<${component} as="code">Hello world</${component}>`)}`,
+      // There is extra whitespace here we don't worry about since formatters would get rid of it
+      output: `${prcImport}${jsx(`<code >Hello world</code>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with single-character 'as' prop`,
+      code: `${prcImport}${jsx(`<${component} as="p">Hello world</${component}>`)}`,
+      output: `${prcImport}${jsx(`<p >Hello world</p>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with string element 'as' prop surrounded by unnecessary braces`,
+      code: `${prcImport}${jsx(`<${component} as={"code"}>Hello world</${component}>`)}`,
+      output: `${prcImport}${jsx(`<code >Hello world</code>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with component reference 'as' prop`,
+      code: `${prcImport}${componentDeclaration}${jsx(`<${component} as={OtherComponent}>Hello world</${component}>`)}`,
+      output: `${prcImport}${componentDeclaration}${jsx(`<OtherComponent >Hello world</OtherComponent>`)}`,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with spread 'as' prop`,
+      code: `${prcImport}${asObjectDeclaration}${jsx(`<${component} {...props}>Hello world</${component}>`)}`,
+      output: null,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `${component} with unusable lowercase reference 'as' prop`,
+      code: `${prcImport}${asConstDeclaration}${jsx(`<${component} as={as}>Hello world</${component}>`)}`,
+      output: null,
+      errors: [{messageId}],
+      filename,
+    },
+    {
+      name: `Non-PRC ${component} when \`skipImportCheck\` is enabled`,
+      code: `${brandImport}${jsx(`<${component}>Hello World</${component}>`)}`,
+      output: `${brandImport}${jsx(`<${replacement}>Hello World</${replacement}>`)}`,
+      filename,
+      errors: [{messageId}],
+      options: [{skipImportCheck: true}],
+    },
+  ]),
+})

package/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 />`,
+    },
+  ],
+})

package/src/rules/no-system-props.js

@@ -46,6 +46,7 @@ const excludedComponentProps = new Map([
   ['ProgressBar', new Set(['bg'])],
   ['PointerBox', new Set(['bg'])],
   ['Truncate', new Set(['maxWidth'])],
+  ['Stack', new Set(['padding', 'gap'])],
 ])
 
 const alwaysExcludedProps = new Set(['variant', 'size'])

package/src/rules/no-unnecessary-components.js

@@ -0,0 +1,160 @@
+// @ts-check
+
+const {ESLintUtils} = require('@typescript-eslint/utils')
+const {IndexKind} = require('typescript')
+const {pick: pickStyledSystemProps} = require('@styled-system/props')
+const {isPrimerComponent} = require('../utils/is-primer-component')
+
+/** @typedef {import('@typescript-eslint/types').TSESTree.JSXAttribute} JSXAttribute */
+
+const components = {
+  Box: {
+    replacement: 'div',
+    messageId: 'unecessaryBox',
+    message: 'Prefer plain HTML elements over `Box` when not using `sx` for styling.',
+    allowedProps: new Set(['sx']), // + styled-system props
+  },
+  Text: {
+    replacement: 'span',
+    messageId: 'unecessarySpan',
+    message: 'Prefer plain HTML elements over `Text` when not using `sx` for styling.',
+    allowedProps: new Set(['sx', 'size', 'weight']), // + styled-system props
+  },
+}
+
+const elementNameRegex = /^[a-z]\w*$/
+const componentNameRegex = /^[A-Z][\w._]*$/
+
+/** @param {string} propName */
+const isStyledSystemProp = propName => propName in pickStyledSystemProps({[propName]: propName})
+
+const rule = ESLintUtils.RuleCreator.withoutDocs({
+  meta: {
+    docs: {
+      description:
+        '`Box` and `Text` should only be used to provide access to the `sx` styling system and have a performance cost. If `sx` props are not being used, prefer `div` and `span` instead.',
+    },
+    messages: {
+      [components.Box.messageId]: components.Box.message,
+      [components.Text.messageId]: components.Text.message,
+    },
+    type: 'problem',
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          skipImportCheck: {
+            type: 'boolean',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    fixable: 'code',
+  },
+  defaultOptions: [{skipImportCheck: false}],
+  create(context) {
+    return {
+      JSXElement({openingElement, closingElement}) {
+        const {name, attributes} = openingElement
+
+        // Ensure this is one of the components we are looking for. Note this doesn't account for import aliases; this
+        // is intentional to avoid having to do the scope tree traversal for every component of every name, which would
+        // be needlessly expensive. We just ignore aliased imports.
+        if (name.type !== 'JSXIdentifier' || !(name.name in components)) return
+        const componentConfig = components[/** @type {keyof typeof components} */ (name.name)]
+
+        // Only continue if the variable declaration is an import from @primer/react. Otherwise it could, for example,
+        // be an import from @primer/brand, which would be valid without sx.
+        const skipImportCheck = context.options[0]?.skipImportCheck
+        const isPrimer = skipImportCheck || isPrimerComponent(name, context.sourceCode.getScope(openingElement))
+        if (!isPrimer) return
+
+        /** @param {string} name */
+        const isAllowedProp = name => componentConfig.allowedProps.has(name) || isStyledSystemProp(name)
+
+        // Validate the attributes and ensure an allowed prop is present or spreaded in
+        /** @type {typeof attributes[number] | undefined | null} */
+        let asProp = undefined
+        for (const attribute of attributes) {
+          // If there is a spread type, check if the type of the spreaded value has an allowed property
+          if (attribute.type === 'JSXSpreadAttribute') {
+            const services = ESLintUtils.getParserServices(context)
+            const typeChecker = services.program.getTypeChecker()
+
+            const spreadType = services.getTypeAtLocation(attribute.argument)
+
+            // Check if the spread type has a string index signature - this could hide an allowed property
+            if (typeChecker.getIndexTypeOfType(spreadType, IndexKind.String) !== undefined) return
+
+            const spreadPropNames = typeChecker.getPropertiesOfType(spreadType).map(prop => prop.getName())
+
+            // If an allowed prop gets spread in, this is a valid use of the component
+            if (spreadPropNames.some(isAllowedProp)) return
+
+            // If there is an `as` inside the spread object, we can't autofix reliably
+            if (spreadPropNames.includes('as')) asProp = null
+
+            continue
+          }
+
+          // Has an allowed prop, so should keep using this component
+          if (attribute.name.type === 'JSXIdentifier' && isAllowedProp(attribute.name.name)) return
+
+          // If there is an `as` prop we will need to account for that when autofixing
+          if (attribute.name.type === 'JSXIdentifier' && attribute.name.name === 'as') asProp = attribute
+        }
+
+        // Determine a replacement component name accounting for the `as` prop if present
+        /** @type {string | null} */
+        let replacement = componentConfig.replacement
+        if (asProp === null) {
+          // {...{as: 'something-unusable'}}
+          replacement = null
+        } else if (asProp?.type === 'JSXAttribute') {
+          // as={ComponentReference}
+          if (asProp.value?.type === 'JSXExpressionContainer' && asProp.value.expression.type === 'Identifier') {
+            // can't just use expression.name here because we want the whole expression if it's A.B
+            const expressionStr = context.sourceCode.getText(asProp.value.expression)
+            replacement = componentNameRegex.test(expressionStr) ? expressionStr : null
+          }
+          // as={'tagName'} (surprisingly common, we really should enable `react/jsx-curly-brace-presence`)
+          else if (
+            asProp.value?.type === 'JSXExpressionContainer' &&
+            asProp.value.expression.type === 'Literal' &&
+            typeof asProp.value.expression.value === 'string' &&
+            elementNameRegex.test(asProp.value.expression.value)
+          ) {
+            replacement = asProp.value.expression.value
+          }
+          // as="tagName"
+          else if (
+            asProp.value?.type === 'Literal' &&
+            typeof asProp.value.value === 'string' &&
+            elementNameRegex.test(asProp.value.value)
+          ) {
+            replacement = asProp.value.value
+          }
+          // too complex to autofix
+          else {
+            replacement = null
+          }
+        }
+
+        context.report({
+          node: name,
+          messageId: componentConfig.messageId,
+          fix: replacement
+            ? function* (fixer) {
+                yield fixer.replaceText(name, replacement)
+                if (closingElement) yield fixer.replaceText(closingElement.name, replacement)
+                if (asProp) yield fixer.remove(asProp)
+              }
+            : undefined,
+        })
+      },
+    }
+  },
+})
+
+module.exports = {...rule, components}

package/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
+          },
+        })
+      },
+    }
+  },
+}

package/src/utils/is-primer-component.js

@@ -1,5 +1,6 @@
 const {isImportedFrom} = require('./is-imported-from')
 
+/** @returns {boolean} */
 function isPrimerComponent(name, scope) {
   let identifier