[New] allow polymorphic linting to be restricted to specified components

[khiga8]

Change

This builds on the setting introduced in #945.

This change allows the consumer to restrict the polymorphic setting to a specified list of components via a new optional setting,polymorphicAllowlist.

• When polymorphicAllowlist is undefined, the polymorphic prop will be used for any components of the prop name specified by polymorphicPropName is present.
• When polymorphicAllowlist is defined, then there is an additional check to make sure that components are part of the polymorphicAllowlist before we use the polymorphic prop specified by polymorphicPropName.

Motivation

Linting components can raise false positives when a component handles behavior that the linter has no way to know.

For example, an Avatar component may render as an img by default and automatically render an alt based on a username. The linter may raise a false positive if Avatar is linted as an img for the alt text lint rule. This can be avoided by not adding the Avatar to the jsx-a11y component map. IfAvatar (for whatever reason) explicitly has as="img" set, since it can also be rendered as an svg, it will end up automatically linted via the polymorphicPropName setting.

In some projects, polymorphic linting may be useful but it may be safer on utility/basic components that don't do much (e.g. a generic Box element), rather than opening it up to any component that allows the polymorphic prop to be set.

I acknowledge that polymorphism is not an ideal pattern that can add complexity (as warned in the README).

[ljharb]

we'll also need documentation.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.84%. Comparing base (882bd4d) to head (dd807b6).

❗ Current head dd807b6 differs from pull request most recent head 2178c5f

Please upload reports for the commit 2178c5f to get more accurate results.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #984      +/-   ##
==========================================
- Coverage   99.03%   98.84%   -0.19%     
==========================================
  Files         107      105       -2     
  Lines        1651     1640      -11     
  Branches      581      580       -1     
==========================================
- Hits         1635     1621      -14     
- Misses         16       19       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[khiga8]

This is ready for another review 🙇‍♀️

[ljharb]

i still find polymorphic components horrific, and i hope you're able to fix your codebase by removing them :-) but let's land this