@arcaauth/eslint-plugin-jsx-a11y 6.10.2

package/docs/rules/alt-text.md

@@ -0,0 +1,168 @@
+# jsx-a11y/alt-text
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
+Enforce that all elements that require alternative text have meaningful information to relay back to the end user. This is a critical component of accessibility for screen reader users in order for them to understand the content's purpose on the page. By default, this rule checks for alternative text on the following elements: `<img>`, `<area>`, `<input type="image">`, and `<object>`.
+
+## How to resolve
+
+### `<img>`
+
+An `<img>` must have the `alt` prop set with meaningful text or as an empty string to indicate that it is an image for decoration.
+
+For images that are being used as icons for a button or control, the `alt` prop should be set to an empty string (`alt=""`).
+
+```jsx
+<button>
+  <img src="icon.png" alt="" />
+  Save
+
+</button>
+```
+
+The content of an `alt` attribute is used to calculate the accessible label of an element, whereas the text content is used to produce a label for the element. For this reason, adding a label to an icon can produce a confusing or duplicated label on a control that already has appropriate text content.
+
+### `<object>`
+
+Add alternative text to all embedded `<object>` elements using either inner text, setting the `title` prop, or using the `aria-label` or `aria-labelledby` props.
+
+### `<input type="image">`
+
+All `<input type="image">` elements must have a non-empty `alt` prop set with a meaningful description of the image or have the `aria-label` or `aria-labelledby` props set.
+
+### `<area>`
+
+All clickable `<area>` elements within an image map have an `alt`, `aria-label` or `aria-labelledby` prop that describes the purpose of the link.
+
+## Rule options
+
+This rule takes one optional object argument of type object:
+
+```json
+{
+    "rules": {
+        "jsx-a11y/alt-text": [ 2, {
+            "elements": [ "img", "object", "area", "input[type=\"image\"]" ],
+            "img": ["Image"],
+            "object": ["Object"],
+            "area": ["Area"],
+            "input[type=\"image\"]": ["InputImage"]
+          }],
+    }
+}
+```
+
+The `elements` option is a whitelist for DOM elements to check for alternative text. If an element is removed from the default set of elements (noted above), any custom components for that component will also be ignored. In order to indicate any custom wrapper components that should be checked, you can map the DOM element to an array of JSX custom components. This is a good use case when you have a wrapper component that simply renders an `img` element, for instance (like in React):
+
+```jsx
+// Image.js
+const Image = props => {
+  const {
+    alt,
+    ...otherProps
+  } = props;
+
+  return (
+    <img alt={alt} {...otherProps} />
+  );
+}
+
+...
+
+// Header.js (for example)
+...
+return (
+  <header>
+    <Image alt="Logo" src="logo.jpg" />
+  </header>
+
+);
+```
+
+Note that passing props as spread attribute without explicitly the necessary accessibility props defined will cause this rule to fail. Explicitly pass down the set of props needed for rule to pass. Use `Image` component above as a reference for destructuring and applying the prop. **It is a good thing to explicitly pass props that you expect to be passed for self-documentation.** For example:
+
+#### Bad
+
+```jsx
+function Foo(props) {
+  return <img {...props} />
+}
+```
+
+#### Good
+
+```jsx
+function Foo({ alt, ...props}) {
+    return <img alt={alt} {...props} />
+}
+
+// OR
+
+function Foo(props) {
+    const {
+        alt,
+
+        ...otherProps
+    } = props;
+
+   return <img alt={alt} {...otherProps} />
+}
+```
+
+### Succeed
+
+```jsx
+<img src="foo" alt="Foo eating a sandwich." />
+<img src="foo" alt={"Foo eating a sandwich."} />
+<img src="foo" alt={altText} />
+<img src="foo" alt={`${person} smiling`} />
+<img src="foo" alt="" />
+
+<object aria-label="foo" />
+<object aria-labelledby="id1" />
+<object>Meaningful description</object>
+<object title="An object" />
+
+<area aria-label="foo" />
+<area aria-labelledby="id1" />
+
+<area alt="This is descriptive!" />
+
+<input type="image" alt="This is descriptive!" />
+<input type="image" aria-label="foo" />
+<input type="image" aria-labelledby="id1" />
+
+```
+
+### Fail
+
+```jsx
+<img src="foo" />
+<img {...props} />
+<img {...props} alt /> // Has no value
+<img {...props} alt={undefined} /> // Has no value
+<img {...props} alt={`${undefined}`} /> // Has no value
+<img src="foo" role="presentation" /> // Avoid ARIA if it can be achieved without
+
+<img src="foo" role="none" /> // Avoid ARIA if it can be achieved without
+
+<object {...props} />
+
+
+<area {...props} />
+
+<input type="image" {...props} />
+```
+
+## Accessibility guidelines
+
+- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
+
+### Resources
+
+- [axe-core, object-alt](https://dequeuniversity.com/rules/axe/3.2/object-alt)
+- [axe-core, image-alt](https://dequeuniversity.com/rules/axe/3.2/image-alt)
+- [axe-core, input-image-alt](https://dequeuniversity.com/rules/axe/3.2/input-image-alt)
+- [axe-core, area-alt](https://dequeuniversity.com/rules/axe/3.2/area-alt)

package/docs/rules/anchor-ambiguous-text.md

@@ -0,0 +1,91 @@
+# jsx-a11y/anchor-ambiguous-text
+
+🚫 This rule is _disabled_ in the ☑️ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+Enforces `<a>` values are not exact matches for the phrases "click here", "here", "link", "a link", or "learn more". Screen readers announce tags as links/interactive, but rely on values for context. Ambiguous anchor descriptions do not provide sufficient context for users.
+
+## Rule options
+
+This rule takes one optional object argument with the parameter `words`.
+
+```json
+{
+  "rules": {
+    "jsx-a11y/anchor-ambiguous-text": [2, {
+      "words": ["click this"],
+    }],
+  }
+}
+```
+
+The `words` option allows users to modify the strings that can be checked for in the anchor text. Useful for specifying other words in other languages. The default value is set by `DEFAULT_AMBIGUOUS_WORDS`:
+
+```js
+const DEFAULT_AMBIGUOUS_WORDS = ['click here', 'here', 'link', 'a link', 'learn more'];
+```
+
+The logic to calculate the inner text of an anchor is as follows:
+
+- if an element has the `aria-label` property, its value is used instead of the inner text
+- if an element has `aria-hidden="true`, it is skipped over
+- if an element is `<img />` or configured to be interpreted like one, its `alt` value is used as its inner text
+
+Note that this rule still disallows ambiguous `aria-label` or `alt` values.
+
+Note that this rule is case-insensitive, trims whitespace, and ignores certain punctuation (`[,.?¿!‽¡;:]`). It only looks for **exact matches**.
+
+### Succeed
+
+```jsx
+<a>read this tutorial</a> // passes since it is not one of the disallowed words
+<a>${here}</a> // this is valid since 'here' is a variable name
+<a aria-label="tutorial on using eslint-plugin-jsx-a11y">click here</a> // the aria-label supersedes the inner text
+```
+
+### Fail
+
+```jsx
+<a>here</a>
+<a>HERE</a>
+<a>link</a>
+<a>click here</a>
+<a>learn more</a>
+<a>learn more.</a>
+<a>learn more,</a>
+<a>learn more?</a>
+<a>learn more!</a>
+<a>learn more:</a>
+<a>learn more;</a>
+<a>a link</a>
+<a> a link </a>
+<a><span> click </span> here</a> // goes through element children
+<a>a<i></i> link</a>
+<a><i></i>a link</a>
+<a><span aria-hidden="true">more text</span>learn more</a> // skips over elements with aria-hidden=true
+<a aria-label="click here">something</a> // the aria-label here is inaccessible
+<a><img alt="click here"/></a> // the alt tag is still ambiguous
+<a alt="tutorial on using eslint-plugin-jsx-a11y">click here</a> // the alt tag is only parsed on img
+```
+
+## Accessibility guidelines
+
+Ensure anchor tags describe the content of the link, opposed to simply describing them as a link.
+
+Compare
+
+```jsx
+<p><a href="#">click here</a> to read a tutorial by Foo Bar</p>
+```
+
+which can be more concise and accessible with
+
+```jsx
+<p>read <a href="#">a tutorial by Foo Bar</a></p>
+```
+
+### Resources
+
+1. [WebAIM, Hyperlinks](https://webaim.org/techniques/hypertext/)
+2. [Deque University, Link Checklist - 'Avoid "link" (or similar) in the link text'](https://dequeuniversity.com/checklists/web/links)

package/docs/rules/anchor-has-content.md

@@ -0,0 +1,64 @@
+# jsx-a11y/anchor-has-content
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
+Enforce that anchors have content and that the content is accessible to screen readers. Accessible means that it is not hidden using the `aria-hidden` prop. Refer to the references to learn about why this is important.
+
+Alternatively, you may use the `title` prop or the `aria-label` prop.
+
+## Rule options
+
+This rule takes one optional object argument of type object:
+
+```json
+{
+    "rules": {
+        "jsx-a11y/anchor-has-content": [ 2, {
+            "components": [ "Anchor" ],
+          }],
+    }
+}
+```
+
+For the `components` option, these strings determine which JSX elements (**always including** `<a>`) should be checked for having content. This is a good use case when you have a wrapper component that simply renders an `a` element (like in React):
+
+```js
+// Anchor.js
+const Anchor = props => {
+  return (
+    <a {...props}>{ props.children }</a>
+  );
+}
+
+...
+
+// CreateAccount.js (for example)
+...
+return (
+  <Anchor>Create Account</Anchor>
+);
+```
+
+
+### Succeed
+```jsx
+<a>Anchor Content!</a>
+<a><TextWrapper /></a>
+<a dangerouslySetInnerHTML={{ __html: 'foo' }} />
+<a title='foo' />
+<a aria-label='foo' />
+```
+
+### Fail
+```jsx
+<a />
+<a><TextWrapper aria-hidden /></a>
+```
+## Accessibility guidelines
+- [WCAG 2.4.4](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context)
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
+
+### Resources
+- [axe-core, link-name](https://dequeuniversity.com/rules/axe/3.2/link-name)

package/docs/rules/anchor-is-valid.md

@@ -0,0 +1,270 @@
+# jsx-a11y/anchor-is-valid
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
+The HTML `<a>` element, with a valid `href` attribute, is formally defined as representing a **hyperlink**. That is, a link between one HTML document and another, or between one location inside an HTML document and another location inside the same document.
+
+In fact, the interactive, underlined `<a>` element has become so synonymous with web navigation that this expectation has become entrenched inside browsers, assistive technologies such as screen readers and in how people generally expect the internet to behave. In short, anchors should navigate.
+
+The use of JavaScript frameworks and libraries, like _React_, has made it very easy to add or subtract functionality from the standard HTML elements. This has led to _anchors_ often being used in applications based on how they look and function instead of what they represent.
+
+Whilst it is possible, for example, to turn the `<a>` element into a fully functional `<button>` element with ARIA, the native user agent implementations of HTML elements are to be preferred over custom ARIA solutions.
+
+## How do I resolve this error?
+
+### Case: I want to perform an action and need a clickable UI element
+
+The native user agent implementations of the `<a>` and `<button>` elements not only differ in how they look and how they act when activated, but also in how the user is expected to interact with them. Both are perfectly clickable when using a mouse, but keyboard users expect `<a>` to activate on `enter` only and `<button>` to activate on _both_ `enter` and `space`.
+
+This is exacerbated by the expectation sighted users have of how _buttons_ and _anchors_ work based on their appearance. Therefore we find that using _anchors_ as _buttons_ can easily create confusion without a relatively complicated ARIA and CSS implementation that only serves to create an element HTML already offers and browsers already implement fully accessibly.
+
+We are aware that sometimes _anchors_ are used instead of _buttons_ to achieve a specific visual design. When using the `<button>` element this can still be achieved with styling but, due to the meaning many people attach to the standard underlined `<a>` due its appearance, please reconsider this in the design.
+
+Consider the following:
+
+```jsx
+<a href="javascript:void(0)" onClick={foo}>Perform action</a>
+<a href="#" onClick={foo}>Perform action</a>
+<a onClick={foo}>Perform action</a>
+```
+
+All these _anchor_ implementations indicate that the element is only used to execute JavaScript code. All the above should be replaced with:
+
+```jsx
+<button onClick={foo}>Perform action</button>
+```
+
+### Case: I want navigable links
+
+An `<a>` element without an `href` attribute no longer functions as a hyperlink. That means that it can no longer accept keyboard focus or be clicked on. The documentation for [no-noninteractive-tabindex](no-noninteractive-tabindex.md) explores this further. Preferably use another element (such as `div` or `span`) for display of text.
+
+To properly function as a hyperlink, the `href` attribute should be present and also contain a valid _URL_. _JavaScript_ strings, empty values or using only **#** are not considered valid `href` values.
+
+Valid `href` attributes values are:
+
+```jsx
+<a href="/some/valid/uri">Navigate to page</a>
+<a href="/some/valid/uri#top">Navigate to page and location</a>
+<a href="#top">Navigate to internal page location</a>
+```
+
+### Case: I need the HTML to be interactive, don't I need to use an a tag for that?
+
+An `<a>` tag is not inherently interactive. Without an href attribute, it really is no different from a `<span>`.
+
+Let's look at an example that is not accessible by all users:
+
+```jsx
+<a
+  className="thing"
+  onMouseEnter={() => this.setState({ showSomething: true })}
+>
+  {label}
+</a>
+```
+
+If you need to create an interface element that the user can click on, consider using a button:
+
+```jsx
+<button
+  className="thing"
+  onClick={() => this.setState({ showSomething: true })}
+>
+  {label}
+</button>
+```
+
+If you want to navigate while providing the user with extra functionality, for example in the `onMouseEnter` event, use an anchor with an `href` attribute containing a URL or path as its value.
+
+```jsx
+<a
+  href={someValidPath}
+  className="thing"
+  onMouseEnter={() => this.setState({ showSomething: true })}
+>
+  {label}
+</a>
+```
+
+If you need to create an interface element that the user can mouse over or mouse out of, consider using a div element. In this case, you may need to apply a role of presentation or an interactive role. Interactive ARIA roles include `button`, `link`, `checkbox`, `menuitem`, `menuitemcheckbox`, `menuitemradio`, `option`, `radio`, `searchbox`, `switch` and `textbox`.
+
+```jsx
+<div
+  role="menuitem"
+  className="thing"
+  onClick={() => this.setState({ showSomething: true })}
+  onMouseEnter={() => this.setState({ showSomething: true })}
+>
+  {label}
+</div>
+```
+
+In the example immediately above an `onClick` event handler was added to provide the same experience mouse users enjoy to keyboard-only and touch-screen users. Never fully rely on mouse events alone to expose functionality.
+
+### Case: I use Next.js and I'm getting this error inside of `<Link>`s
+
+This is a [known issue](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/issues/402) with Next.js's decision to construct internal links by nesting an href-free `<a>` tag inside of a `<Link>` component. Next.js is also [aware of the issue](https://github.com/vercel/next.js/issues/5533) and has an [RFC](https://github.com/vercel/next.js/discussions/8207) working towards a solution.
+
+Until the Next.js API can be updated to a more performant and standard setup, you have a few workaround options:
+
+1. If you have only a few `Link`s, or they're clustered in just a few files like `nav.tsx`, you can use disable macros like `{/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}` to turn off validation of this rule for those usages.
+
+2. You can use the `Link` component's `passHref` prop to override a dummy `href` on the `<a>`:
+```typescript
+<Link href="/my-amazing-page" passHref>
+  <a href="replace">Go to my amazing page</a>
+</Link>
+```
+
+3. You can invest in a custom component that wraps the creation of the `Link` and `a`. You can then add your new custom component to the list of components to validate to ensure that your links are all created with a navigable href. A sample custom component is shared [here](https://gist.github.com/zackdotcomputer/d7af9901e7db87364aad7fbfadb5c99b) and it would be used like this:
+```typescript
+// Internally, LinkTo handles the making of the Link and A, collecting the
+// need for a lint workaround into a single file.
+// Externally, LinkTo can be linted using this rule, ensuring it will always
+// have a valid href prop.
+<LinkTo href="/my-amazing-page">Go to my amazing page</LinkTo>
+```
+
+### Case: I understand the previous cases but still need an element resembling a link that is purely clickable
+
+We recommend, without reserve, that elements resembling anchors should navigate. This will provide a superior user experience to a larger group of users out there.
+
+However, we understand that developers are not always in total control of the visual design of web applications. In cases where it is imperative to provide an element resembling an anchor that purely acts as a click target with no navigation as result, we would like to recommend a compromise.
+
+Again change the element to a `<button>`:
+
+```jsx
+<button
+  type="button"
+  className="link-button"
+  onClick={() => this.setState({ showSomething: true })}
+>
+  Press me, I look like a link
+</button>
+```
+
+Then use styling to change its appearance to that of a link:
+
+```css
+.link-button {
+  background-color: transparent;
+  border: none;
+  cursor: pointer;
+  text-decoration: underline;
+  display: inline;
+  margin: 0;
+  padding: 0;
+}
+```
+
+This button element can now also be used inline in text.
+
+Once again we stress that this is an inferior implementation and some users will encounter difficulty to use your website, however, it will allow a larger group of people to interact with your website than the alternative of ignoring the rule's warning.
+
+## Rule options
+
+This rule takes one optional object argument of type object:
+
+```json
+{
+  "rules": {
+    "jsx-a11y/anchor-is-valid": [
+      "error",
+      {
+        "components": ["Link"],
+        "specialLink": ["hrefLeft", "hrefRight"],
+        "aspects": ["noHref", "invalidHref", "preferButton"]
+      }
+    ]
+  }
+}
+```
+
+For the `components` option, these strings determine which JSX elements (**always including** `<a>`) should be checked for the props designated in the `specialLink` options (**always including** `href`). This is a good use case when you have a wrapper component that simply renders an `<a>` element (like in React):
+
+```js
+// Link.js
+const Link = props => <a {...props}>A link</a>;
+
+...
+
+// NavBar.js (for example)
+...
+return (
+  <nav>
+    <Link href="/home" />
+  </nav>
+);
+```
+
+For the `aspects` option, these strings determine which sub-rules are run. This allows omission of certain error types in restrictive environments.
+
+- `noHref`: Checks whether an anchor contains an `href` attribute.
+- `invalidHref`: Checks if a given `href` value is valid.
+- `preferButton`: Checks if anchors have been used as buttons.
+
+The option can be used on its own or with the `components` and `specialLink` options.
+
+If omitted, all sub-rule aspects will be run by default. This is the recommended configuration for all cases except where the rule becomes unusable due to well founded restrictions.
+
+The option must contain at least one `aspect`.
+
+### Succeed
+
+```jsx
+<a href="https://github.com" />
+<a href="#section" />
+<a href="foo" />
+<a href="/foo/bar" />
+<a href={someValidPath} />
+<a href="https://github.com" onClick={foo} />
+<a href="#section" onClick={foo} />
+<a href="foo" onClick={foo} />
+<a href="/foo/bar" onClick={foo} />
+<a href={someValidPath} onClick={foo} />
+```
+
+### Fail
+
+Anchors should be a button:
+
+```jsx
+<a onClick={foo} />
+<a href="#" onClick={foo} />
+<a href={"#"} onClick={foo} />
+<a href={`#`} onClick={foo} />
+<a href="javascript:void(0)" onClick={foo} />
+<a href={"javascript:void(0)"} onClick={foo} />
+<a href={`javascript:void(0)`} onClick={foo} />
+```
+
+Missing `href` attribute:
+
+```jsx
+<a />
+<a href={undefined} />
+<a href={null} />
+```
+
+Invalid `href` attribute:
+
+```jsx
+<a href="#" />
+<a href={"#"} />
+<a href={`#`} />
+<a href="javascript:void(0)" />
+<a href={"javascript:void(0)"} />
+<a href={`javascript:void(0)`} />
+```
+
+## Accessibility guidelines
+
+- [WCAG 2.1.1](https://www.w3.org/WAI/WCAG21/Understanding/keyboard)
+
+### Resources
+
+- [WebAIM - Introduction to Links and Hypertext](https://webaim.org/techniques/hypertext/)
+- [Links vs. Buttons in Modern Web Applications](https://marcysutton.com/links-vs-buttons-in-modern-web-applications/)
+- [Using ARIA - Notes on ARIA use in HTML](https://www.w3.org/TR/using-aria/#NOTES)

package/docs/rules/aria-activedescendant-has-tabindex.md

@@ -0,0 +1,52 @@
+# jsx-a11y/aria-activedescendant-has-tabindex
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
+`aria-activedescendant` is used to manage focus within a [composite widget](https://www.w3.org/TR/wai-aria/#composite).
+The element with the attribute `aria-activedescendant` retains the active document
+focus; it indicates which of its child elements has secondary focus by assigning
+the ID of that element to the value of `aria-activedescendant`. This pattern is
+used to build a widget like a search typeahead select list. The search input box
+retains document focus so that the user can type in the input. If the down arrow
+key is pressed and a search suggestion is highlighted, the ID of the suggestion
+element will be applied as the value of `aria-activedescendant` on the input
+element.
+
+Because an element with `aria-activedescendant` must be tabbable, it must either
+have an inherent `tabIndex` of zero or declare a `tabIndex` attribute.
+
+## Rule details
+
+This rule takes no arguments.
+
+### Succeed
+```jsx
+<CustomComponent />
+<CustomComponent aria-activedescendant={someID} />
+<CustomComponent aria-activedescendant={someID} tabIndex={0} />
+<CustomComponent aria-activedescendant={someID} tabIndex={-1} />
+<div />
+<input />
+<div tabIndex={0} />
+<div aria-activedescendant={someID} tabIndex={0} />
+<div aria-activedescendant={someID} tabIndex="0" />
+<div aria-activedescendant={someID} tabIndex={1} />
+<div aria-activedescendant={someID} tabIndex={-1} />
+<div aria-activedescendant={someID} tabIndex="-1" />
+<input aria-activedescendant={someID} />
+<input aria-activedescendant={someID} tabIndex={0} />
+<input aria-activedescendant={someID} tabIndex={-1} />
+```
+
+### Fail
+```jsx
+<div aria-activedescendant={someID} />
+```
+
+## Accessibility guidelines
+General best practice (reference resources)
+
+### Resources
+- [MDN, Using the aria-activedescendant attribute](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-activedescendant_attribute)

package/docs/rules/aria-props.md

@@ -0,0 +1,29 @@
+# jsx-a11y/aria-props
+
+💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
+
+<!-- end auto-generated rule header -->
+
+Elements cannot use an invalid ARIA attribute. This will fail if it finds an `aria-*` property that is not listed in [WAI-ARIA States and Properties spec](https://www.w3.org/WAI/PF/aria-1.1/states_and_properties).
+
+## Rule details
+
+This rule takes no arguments.
+
+### Succeed
+```jsx
+<!-- Good: Labeled using correctly spelled aria-labelledby -->
+<div id="address_label">Enter your address</div>
+<input aria-labelledby="address_label">
+```
+
+### Fail
+
+```jsx
+<!-- Bad: Labeled using incorrectly spelled aria-labeledby -->
+<div id="address_label">Enter your address</div>
+<input aria-labeledby="address_label">
+```
+
+## Accessibility guidelines
+- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)