Skip to content

Commit accbf80

Browse files
infofarmerinfofarmer
authored
Add files via upload
0 parents  commit accbf80

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+3354
-0
lines changed

Diff for: ‎CHANGELOG.md

+659
Large diffs are not rendered by default.

Diff for: ‎CONTRIBUTING.md

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
# Contributing to ``eslint-plugin-jsx-a11y``
3+
4+
Thank you for your interest in ``eslint-plugin-jsx-a11y``. [Here](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) you can find the issues that are ready for contributions.
5+
6+
Please refer to the [following](https://github.com/jsx-eslint/.github/blob/HEAD/CONTRIBUTING.md) for further information.

Diff for: ‎docs/rules/accessible-emoji.md

+30
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# jsx-a11y/accessible-emoji
2+
3+
❌ This rule is deprecated.
4+
5+
<!-- end auto-generated rule header -->
6+
7+
Emoji have become a common way of communicating content to the end user. To a person using a screenreader, however, they may not be aware that this content is there at all. By wrapping the emoji in a `<span>`, giving it the `role="img"`, and providing a useful description in `aria-label`, the screenreader will treat the emoji as an image in the accessibility tree with an accessible name for the end user.
8+
9+
## Rule details
10+
11+
This rule takes no arguments.
12+
13+
### Succeed
14+
```jsx
15+
<span role="img" aria-label="Snowman">&#9731;</span>
16+
<span role="img" aria-label="Panda">🐼</span>
17+
<span role="img" aria-labelledby="panda1">🐼</span>
18+
```
19+
20+
### Fail
21+
```jsx
22+
<span>🐼</span>
23+
<i role="img" aria-label="Panda">🐼</i>
24+
```
25+
26+
## Accessibility guidelines
27+
- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
28+
29+
### Resources
30+
- [Léonie Watson, Accessible Emoji](https://tink.uk/accessible-emoji/)

Diff for: ‎docs/rules/alt-text.md

+168
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
# jsx-a11y/alt-text
2+
3+
💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
4+
5+
<!-- end auto-generated rule header -->
6+
7+
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>`.
8+
9+
## How to resolve
10+
11+
### `<img>`
12+
13+
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.
14+
15+
For images that are being used as icons for a button or control, the `alt` prop should be set to an empty string (`alt=""`).
16+
17+
```jsx
18+
<button>
19+
<img src="icon.png" alt="" />
20+
Save
21+
22+
</button>
23+
```
24+
25+
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.
26+
27+
### `<object>`
28+
29+
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.
30+
31+
### `<input type="image">`
32+
33+
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.
34+
35+
### `<area>`
36+
37+
All clickable `<area>` elements within an image map have an `alt`, `aria-label` or `aria-labelledby` prop that describes the purpose of the link.
38+
39+
## Rule options
40+
41+
This rule takes one optional object argument of type object:
42+
43+
```json
44+
{
45+
"rules": {
46+
"jsx-a11y/alt-text": [ 2, {
47+
"elements": [ "img", "object", "area", "input[type=\"image\"]" ],
48+
"img": ["Image"],
49+
"object": ["Object"],
50+
"area": ["Area"],
51+
"input[type=\"image\"]": ["InputImage"]
52+
}],
53+
}
54+
}
55+
```
56+
57+
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):
58+
59+
```jsx
60+
// Image.js
61+
const Image = props => {
62+
const {
63+
alt,
64+
...otherProps
65+
} = props;
66+
67+
return (
68+
<img alt={alt} {...otherProps} />
69+
);
70+
}
71+
72+
...
73+
74+
// Header.js (for example)
75+
...
76+
return (
77+
<header>
78+
<Image alt="Logo" src="logo.jpg" />
79+
</header>
80+
81+
);
82+
```
83+
84+
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:
85+
86+
#### Bad
87+
88+
```jsx
89+
function Foo(props) {
90+
return <img {...props} />
91+
}
92+
```
93+
94+
#### Good
95+
96+
```jsx
97+
function Foo({ alt, ...props}) {
98+
return <img alt={alt} {...props} />
99+
}
100+
101+
// OR
102+
103+
function Foo(props) {
104+
const {
105+
alt,
106+
107+
...otherProps
108+
} = props;
109+
110+
return <img alt={alt} {...otherProps} />
111+
}
112+
```
113+
114+
### Succeed
115+
116+
```jsx
117+
<img src="foo" alt="Foo eating a sandwich." />
118+
<img src="foo" alt={"Foo eating a sandwich."} />
119+
<img src="foo" alt={altText} />
120+
<img src="foo" alt={`${person} smiling`} />
121+
<img src="foo" alt="" />
122+
123+
<object aria-label="foo" />
124+
<object aria-labelledby="id1" />
125+
<object>Meaningful description</object>
126+
<object title="An object" />
127+
128+
<area aria-label="foo" />
129+
<area aria-labelledby="id1" />
130+
131+
<area alt="This is descriptive!" />
132+
133+
<input type="image" alt="This is descriptive!" />
134+
<input type="image" aria-label="foo" />
135+
<input type="image" aria-labelledby="id1" />
136+
137+
```
138+
139+
### Fail
140+
141+
```jsx
142+
<img src="foo" />
143+
<img {...props} />
144+
<img {...props} alt /> // Has no value
145+
<img {...props} alt={undefined} /> // Has no value
146+
<img {...props} alt={`${undefined}`} /> // Has no value
147+
<img src="foo" role="presentation" /> // Avoid ARIA if it can be achieved without
148+
149+
<img src="foo" role="none" /> // Avoid ARIA if it can be achieved without
150+
151+
<object {...props} />
152+
153+
154+
<area {...props} />
155+
156+
<input type="image" {...props} />
157+
```
158+
159+
## Accessibility guidelines
160+
161+
- [WCAG 1.1.1](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html)
162+
163+
### Resources
164+
165+
- [axe-core, object-alt](https://dequeuniversity.com/rules/axe/3.2/object-alt)
166+
- [axe-core, image-alt](https://dequeuniversity.com/rules/axe/3.2/image-alt)
167+
- [axe-core, input-image-alt](https://dequeuniversity.com/rules/axe/3.2/input-image-alt)
168+
- [axe-core, area-alt](https://dequeuniversity.com/rules/axe/3.2/area-alt)

Diff for: ‎docs/rules/anchor-ambiguous-text.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# jsx-a11y/anchor-ambiguous-text
2+
3+
🚫 This rule is _disabled_ in the ☑️ `recommended` config.
4+
5+
<!-- end auto-generated rule header -->
6+
7+
Enforces `<a>` values are not exact matches for the phrases "click here", "here", "link", "a link", or "learn more". Screenreaders announce tags as links/interactive, but rely on values for context. Ambiguous anchor descriptions do not provide sufficient context for users.
8+
9+
## Rule options
10+
11+
This rule takes one optional object argument with the parameter `words`.
12+
13+
```json
14+
{
15+
"rules": {
16+
"jsx-a11y/anchor-ambiguous-text": [2, {
17+
"words": ["click this"],
18+
}],
19+
}
20+
}
21+
```
22+
23+
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`:
24+
25+
```js
26+
const DEFAULT_AMBIGUOUS_WORDS = ['click here', 'here', 'link', 'a link', 'learn more'];
27+
```
28+
29+
The logic to calculate the inner text of an anchor is as follows:
30+
31+
- if an element has the `aria-label` property, its value is used instead of the inner text
32+
- if an element has `aria-hidden="true`, it is skipped over
33+
- if an element is `<img />` or configured to be interpreted like one, its `alt` value is used as its inner text
34+
35+
Note that this rule still disallows ambiguous `aria-label` or `alt` values.
36+
37+
Note that this rule is case-insensitive, trims whitespace, and ignores certain punctuation (`[,.?¿!‽¡;:]`). It only looks for **exact matches**.
38+
39+
### Succeed
40+
41+
```jsx
42+
<a>read this tutorial</a> // passes since it is not one of the disallowed words
43+
<a>${here}</a> // this is valid since 'here' is a variable name
44+
<a aria-label="tutorial on using eslint-plugin-jsx-a11y">click here</a> // the aria-label supersedes the inner text
45+
```
46+
47+
### Fail
48+
49+
```jsx
50+
<a>here</a>
51+
<a>HERE</a>
52+
<a>link</a>
53+
<a>click here</a>
54+
<a>learn more</a>
55+
<a>learn more.</a>
56+
<a>learn more,</a>
57+
<a>learn more?</a>
58+
<a>learn more!</a>
59+
<a>learn more:</a>
60+
<a>learn more;</a>
61+
<a>a link</a>
62+
<a> a link </a>
63+
<a><span> click </span> here</a> // goes through element children
64+
<a>a<i></i> link</a>
65+
<a><i></i>a link</a>
66+
<a><span aria-hidden="true">more text</span>learn more</a> // skips over elements with aria-hidden=true
67+
<a aria-label="click here">something</a> // the aria-label here is inaccessible
68+
<a><img alt="click here"/></a> // the alt tag is still ambiguous
69+
<a alt="tutorial on using eslint-plugin-jsx-a11y">click here</a> // the alt tag is only parsed on img
70+
```
71+
72+
## Accessibility guidelines
73+
74+
Ensure anchor tags describe the content of the link, opposed to simply describing them as a link.
75+
76+
Compare
77+
78+
```jsx
79+
<p><a href="#">click here</a> to read a tutorial by Foo Bar</p>
80+
```
81+
82+
which can be more concise and accessible with
83+
84+
```jsx
85+
<p>read <a href="#">a tutorial by Foo Bar</a></p>
86+
```
87+
88+
### Resources
89+
90+
1. [WebAIM, Hyperlinks](https://webaim.org/techniques/hypertext/)
91+
2. [Deque University, Link Checklist - 'Avoid "link" (or similar) in the link text'](https://dequeuniversity.com/checklists/web/links)

Diff for: ‎docs/rules/anchor-has-content.md

+60
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# jsx-a11y/anchor-has-content
2+
3+
💼 This rule is enabled in the following configs: ☑️ `recommended`, 🔒 `strict`.
4+
5+
<!-- end auto-generated rule header -->
6+
7+
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.
8+
9+
## Rule options
10+
11+
This rule takes one optional object argument of type object:
12+
13+
```json
14+
{
15+
"rules": {
16+
"jsx-a11y/anchor-has-content": [ 2, {
17+
"components": [ "Anchor" ],
18+
}],
19+
}
20+
}
21+
```
22+
23+
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):
24+
25+
```js
26+
// Anchor.js
27+
const Anchor = props => {
28+
return (
29+
<a {...props}>{ props.children }</a>
30+
);
31+
}
32+
33+
...
34+
35+
// CreateAccount.js (for example)
36+
...
37+
return (
38+
<Anchor>Create Account</Anchor>
39+
);
40+
```
41+
42+
43+
### Succeed
44+
```jsx
45+
<a>Anchor Content!</a>
46+
<a><TextWrapper /></a>
47+
<a dangerouslySetInnerHTML={{ __html: 'foo' }} />
48+
```
49+
50+
### Fail
51+
```jsx
52+
<a />
53+
<a><TextWrapper aria-hidden /></a>
54+
```
55+
## Accessibility guidelines
56+
- [WCAG 2.4.4](https://www.w3.org/WAI/WCAG21/Understanding/link-purpose-in-context)
57+
- [WCAG 4.1.2](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value)
58+
59+
### Resources
60+
- [axe-core, link-name](https://dequeuniversity.com/rules/axe/3.2/link-name)

0 commit comments

Comments
 (0)