add docs and htmlPropName

Author: kendallgassner

docs/rules/a11y-no-visually-hidden-interactive-element.md

@@ -6,6 +6,23 @@
 
 This rule guards against visually hiding interactive elements. If a sighted keyboard user navigates to an interactive element that is visually hidden they might become confused and assume that keyboard focus has been lost.
 
+Note: we are not guarding against visually hidden `input` elements at this time. Some visually hidden inputs might cause a false positive (e.g. some file inputs).
+
+### Why do we visually hide content?
+
+Visually hiding content can be useful when you want to provide information specifically to screen reader users or other assitive technology users while keeping content hidden from sighted users.
+
+Applying the following css will visually hide content while still making it accessible to screen reader users.
+
+```css
+clip-path: inset(50%);
+height: 1px;
+overflow: hidden;
+position: absolute;
+white-space: nowrap;
+width: 1px;
+```
+
 👎 Examples of **incorrect** code for this rule:
 
 ```jsx
@@ -40,13 +57,18 @@ This rule guards against visually hiding interactive elements. If a sighted keyb
 
 ## Options
 
+- className - A css className that visually hides content. Defaults to `sr-only`.
+- componentName - A react component name that visually hides content. Defaults to `VisuallyHidden`.
+- htmlPropName - A prop name used to replace the semantic element that is rendered. Defaults to `as`.
+
 ```json
 {
   "a11y-no-visually-hidden-interactive-element": [
     "error",
     {
       "className": "visually-hidden",
-      "componentName": "VisuallyHidden"
+      "componentName": "VisuallyHidden",
+      "htmlPropName": "as"
     }
   ]
 }

lib/rules/a11y-no-visually-hidden-interactive-element.js

@@ -4,10 +4,12 @@ const {generateObjSchema} = require('eslint-plugin-jsx-a11y/lib/util/schemas')
 
 const defaultClassName = 'sr-only'
 const defaultcomponentName = 'VisuallyHidden'
+const defaultHtmlPropName = 'as'
 
 const schema = generateObjSchema({
   className: {type: 'string'},
   componentName: {type: 'string'},
+  htmlPropName: {type: 'string'},
 })
 
 /** Note: we are not including input elements at this time
@@ -16,9 +18,9 @@ const schema = generateObjSchema({
  */
 const INTERACTIVELEMENTS = ['a', 'button', 'summary', 'select', 'option', 'textarea']
 
-const checkIfInteractiveElement = (context, node) => {
+const checkIfInteractiveElement = (context, htmlPropName, node) => {
   const elementType = getElementType(context, node.openingElement)
-  const asProp = getPropValue(getProp(node.openingElement.attributes, 'as'))
+  const asProp = getPropValue(getProp(node.openingElement.attributes, htmlPropName))
 
   for (const interactiveElement of INTERACTIVELEMENTS) {
     if ((asProp ?? elementType) === interactiveElement) {
@@ -29,29 +31,24 @@ const checkIfInteractiveElement = (context, node) => {
 }
 
 // if the node is visually hidden recursively check if it has interactive children
-const checkIfVisuallyHiddenAndInteractive = (context, className, componentName, node, isParentVisuallyHidden) => {
+const checkIfVisuallyHiddenAndInteractive = (context, options, node, isParentVisuallyHidden) => {
+  const {className, componentName, htmlPropName} = options
   if (node.type === 'JSXElement') {
     const classes = getPropValue(getProp(node.openingElement.attributes, 'className'))
     const isVisuallyHiddenElement = node.openingElement.name.name === componentName
     const hasSROnlyClass = typeof classes !== 'undefined' && classes.includes(className)
     let isHidden = false
 
     if (hasSROnlyClass || isVisuallyHiddenElement || !!isParentVisuallyHidden) {
-      if (checkIfInteractiveElement(context, node)) {
+      if (checkIfInteractiveElement(context, htmlPropName, node)) {
         return true
       }
       isHidden = true
     }
     if (node.children && node.children.length > 0) {
       return (
         typeof node.children?.find(child =>
-          checkIfVisuallyHiddenAndInteractive(
-            context,
-            className,
-            componentName,
-            child,
-            !!isParentVisuallyHidden || isHidden,
-          ),
+          checkIfVisuallyHiddenAndInteractive(context, options, child, !!isParentVisuallyHidden || isHidden),
         ) !== 'undefined'
       )
     }
@@ -73,10 +70,11 @@ module.exports = {
     const config = options[0] || {}
     const className = config.className || defaultClassName
     const componentName = config.componentName || defaultcomponentName
+    const htmlPropName = config.htmlPropName || defaultHtmlPropName
 
     return {
       JSXElement: node => {
-        if (checkIfVisuallyHiddenAndInteractive(context, className, componentName, node, false)) {
+        if (checkIfVisuallyHiddenAndInteractive(context, {className, componentName, htmlPropName}, node, false)) {
           context.report({
             node,
             message: