Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

ARIA state or property: various editorial improvements #2012

Merged
merged 13 commits into from
Apr 6, 2023
Merged

ARIA state or property: various editorial improvements #2012

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
8523275
ARIA state or property: various editorial improvements
WilcoFiers Jan 18, 2023
914a18f
Update aria-state-or-property-valid-value-6a7281.md
WilcoFiers Jan 18, 2023
26a5339
Apply suggestions from code review
WilcoFiers Jan 19, 2023
b2987df
Add collapsed combobox exception
WilcoFiers Jan 24, 2023
bc8d654
Test issue
WilcoFiers Jan 24, 2023
0c53ecc
Editorial
WilcoFiers Jan 24, 2023
4a65e35
Update _rules/aria-state-or-property-valid-value-6a7281.md
WilcoFiers Jan 24, 2023
ee831ec
Apply suggestions from code review
WilcoFiers Feb 9, 2023
ac744e8
Remove ID Reference requirements
WilcoFiers Mar 2, 2023
194f3ca
Address comments
WilcoFiers Mar 2, 2023
083aecc
Apply suggestions from code review
WilcoFiers Mar 30, 2023
d7ea035
fix failing test
WilcoFiers Mar 30, 2023
a64484b
Merge branch 'develop' into aria-idref
WilcoFiers Apr 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 47 additions & 93 deletions _rules/aria-state-or-property-valid-value-6a7281.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,31 +28,27 @@ acknowledgments:

## Applicability

This rule applies to any [WAI-ARIA 1.2 state or property](https://www.w3.org/TR/wai-aria-1.2/#state_prop_def) that is not empty (""), and that is specified on an [HTML or SVG element][].
This rule applies to any [WAI-ARIA state or property][] that has a non-empty ("") [attribute value][], and that is specified on an [HTML or SVG element][].

## Expectation

Each test target has a valid value according to its [WAI-ARIA 1.2 value type](https://www.w3.org/TR/wai-aria-1.2/#propcharacteristic_value).
Each test target has an [attribute value][] that is valid according to its [WAI-ARIA value type][value type].

For value types `ID Reference` and `ID Reference List` for [WAI-ARIA required properties](https://www.w3.org/TR/wai-aria-1.2/#requiredState) at least one of the elements with the given ids exists in the same [document tree](https://dom.spec.whatwg.org/#document-trees) or in the same [shadow tree](https://dom.spec.whatwg.org/#shadow-trees) as the element that specifies the target attribute.

For value type `URI` the value matches the [generic URI syntax](https://www.ietf.org/rfc/rfc3986.txt).
**Exception**: For value types `ID Reference` and `ID Reference List` no ID referenced elements are required.

## Assumptions

This rule catches values that are undefined in [WAI-ARIA Specifications][], and where the resulting behavior in user agents are also undefined in WAI-ARIA. This might lead to accessibility issues, if the intention was to use behavior defined in [WAI-ARIA Specifications][]. When values are used that do not have a defined behavior in [WAI-ARIA Specifications][], the HTML/SVG specification decides what default values should be used, since it is defined here what should happen when an invalid value is used for an attribute. If the default value for invalid attribute values happens to match the author's intention for the value, there will not be an accessibility issue.
There are no assumptions.

## Accessibility Support

Some user agents treat the value of `aria-*` attribute as case-sensitive (even when these are not ID) while some treat them as case-insensitive.

## Background

Using invalid ARIA attribute values is often the result of a typo or other developer error. These attributes are then either ignored, or a default value is assumed by browsers and assistive technologies. This often means that a state or property which should exist is missing or has an unexpected value. This can cause issues under [success criterion 1.3.1 Info and Relationships][sc131] or [4.1.2 Name, Rule Value][sc412].

Only for [WAI-ARIA required properties](https://www.w3.org/TR/wai-aria-1.2/#requiredState) with value types `ID Reference` and `ID Reference List` is there a requirement that the elements with the given ids actually exists. For non-required properties, this is not a requirement. For example, the value of the `aria-errormessage` attribute on an `input` does not need to reference an `id` that exists within the same document, because an [HTML element](https://html.spec.whatwg.org/#htmlelement) with such and `id` may be created in response to an [event](https://dom.spec.whatwg.org/#event) that may or may not happen.
Using invalid ARIA attribute values is often the result of a typo or other developer error. These attributes are then either ignored, or a default value is assumed by browsers and assistive technologies. This often means that a state or property which should exist is missing or has an unexpected value. This can cause issues under [success criterion 1.3.1 Info and Relationships][sc131] or [4.1.2 Name, Rule Value][sc412]. If the default value for invalid attribute values happens to match the author's intention for the value, there will not be an accessibility issue.
WilcoFiers marked this conversation as resolved.
Show resolved Hide resolved

For value type `URI`, this rule does not require that the destination URI exists.
This rule does not require the target of an `ID Reference` to exist. This is because referencing an element that does not exist, and not having the reference at all has the same end result. A common use case for using `ID Reference` for a non-existing ID is to use a static `aria-errormessage` on an `input` element, and to only insert the element with the error message if there is an actual error. There are some cases in which ID references are required. These are tested in a separate rule.

### Related rules

Expand All @@ -72,184 +68,143 @@ For value type `URI`, this rule does not require that the destination URI exists

#### Passed Example 1

`aria-required` property with valid true/false value
The `aria-label` [attribute value][] of `Family name` is allowed for the `string` [value type][].

```html
<div role="textbox" aria-required="true" aria-label="A required textbox"></div>
<div role="textbox" aria-label="Family name"></div>
```

#### Passed Example 2

`aria-expanded` state with valid true/false/undefined value
The `aria-required` [attribute value][] of `true` is allowed for the `true/false` [value type][].

```html
<div role="button" aria-expanded="undefined">A button</div>
<div role="textbox" aria-required="true" aria-label="Family name"></div>
```

#### Passed Example 3

`aria-pressed` state with valid tristate value
The `aria-expanded` [attribute value][] of `undefined` is allowed for the `true/false/undefined` [value type][].

```html
<div role="button" aria-pressed="mixed">An other button</div>
<div role="button" aria-expanded="undefined">A button</div>
```

#### Passed Example 4

`aria-errormessage` property with valid ID reference value
The `aria-pressed` [attribute value][] of `mixed` is allowed for the `tristate` [value type][].

```html
<div role="textbox" aria-errormessage="my-error" aria-label="A textbox"></div>
<div role="button" aria-pressed="mixed">Partially pressed button</div>
```

#### Passed Example 5

`aria-owns` property with valid ID reference list value
The `aria-errormessage` [attribute value][] is an `ID Reference` [value type][]. The presence of an element with a matching ID is not required by this rule.

```html
<h1>Shopping list</h1>
<div role="list" aria-owns="item1 item2"></div>
<div id="item1">Apples</div>
<div id="item2">Bananas</div>
<div role="textbox" aria-errormessage="my-error" aria-label="A textbox"></div>
```

#### Passed Example 6

`aria-rowindex` property with valid integer value
The `aria-owns` [attribute value][] is a valid `ID Reference List` [value type][]. Both tokens reference elements that exist in the same [DOM tree][].

```html
<div role="gridcell" aria-rowindex="2">Fred</div>
<h1>Shopping list</h1>
<div role="list" aria-owns="item1 item2"></div>
<div id="item1">Apples</div>
<div id="item2">Bananas</div>
```

#### Passed Example 7

`aria-valuemin`, `aria-valuemax` and `aria-valuenow` properties with valid number values
The `aria-rowindex` [attribute value][] of 2 is a valid `integer` [value type][].

```html
<div role="spinbutton" aria-valuemin="1.0" aria-valuemax="2.0" aria-valuenow="1.5" aria-label="Select a value"></div>
<div role="gridcell" aria-rowindex="2">Fred</div>
```

#### Passed Example 8

`aria-placeholder` property with valid string value
The `aria-valuemin`, `aria-valuemax` and `aria-valuenow` [attribute values][attribute value] are valid for a `number` [value type][].

```html
<div role="textbox" aria-placeholder="MM-DD-YYYY" aria-label="Your birthdate">
MM-DD-YYYY
</div>
<div role="spinbutton" aria-valuemin="1.0" aria-valuemax="2.0" aria-valuenow="1.5" aria-label="Select a value"></div>
```

#### Passed Example 9

`aria-relevant` property with valid token list values
The `aria-current` [attribute value][] of `page` is a valid `token` [value type][].

```html
<div role="alert" aria-relevant="text removals"></div>
<a href="/" aria-current="page">Home</a>
```

#### Passed Example 10

`aria-controls`, which is a required property for the role `scrollbar`, has `ID Reference list` that references at least one element existing in the same document tree.
The `aria-relevant` [attribute value][] has a `text` and `removals` tokens. Both are valid tokens for a `aria-relevant` `token list` [value type][].

```html
<div id="content1">Lorem ipsum...</div>
<div
role="scrollbar"
aria-controls="content1 content2"
aria-orientation="vertical"
aria-valuemax="100"
aria-valuemin="0"
aria-valuenow="25"
></div>
<div role="alert" aria-relevant="text removals"></div>
```

### Failed

#### Failed Example 1

`aria-required` property with invalid true/false value
The `aria-required` [attribute value][] of `undefined` is not valid for a `true/false` [value type][].

```html
<div role="textbox" aria-required="undefined" aria-label="A required textbox"></div>
```

#### Failed Example 2

`aria-expanded` state with invalid true/false/undefined value
The `aria-expanded` [attribute value][] of `collapsed` is not valid for a `true/false/undefined` [value type][].

```html
<div role="button" aria-expanded="mixed">A button</div>
<div role="button" aria-expanded="collapsed">A button</div>
```

#### Failed Example 3

`aria-pressed` state with invalid tristate value
The `aria-pressed` [attribute value][] of `horizontal` is not valid for a `tristate` [value type][].

```html
<div role="button" aria-pressed="horizontal">An other button</div>
```

#### Failed Example 4

`aria-errormessage` property with invalid ID reference value, since space is not allowed in a single ID
The `aria-rowindex` [attribute value][] of `2.5` is not valid for an `integer` [value type][] because it is a decimal number.

```html
<div role="textbox" aria-errormessage="error1 error2" aria-label="A textbox with an error"></div>
<div role="gridcell" aria-rowindex="2.5">Fred</div>
```

#### Failed Example 5

`aria-rowindex` property with invalid integer value
The `aria-valuemin`, `aria-valuemax` and `aria-valuenow` [attribute values][attribute value] are `strings`. These should all be of the `number` [value type][] instead.

```html
<div role="gridcell" aria-rowindex="2.5">Fred</div>
<div role="spinbutton" aria-valuemin="one" aria-valuemax="three" aria-valuenow="two" aria-label="Choose a value"></div>
```

#### Failed Example 6

`aria-valuemin`, `aria-valuemax` and `aria-valuenow` property with invalid number values
The `aria-live` [attribute value][] of `page` is not a valid `token`, because `page` is not a token for `aria-live`.

```html
<div role="spinbutton" aria-valuemin="one" aria-valuemax="three" aria-valuenow="two" aria-label="Choose a value"></div>
<div role="main" aria-live="page"></div>
```

#### Failed Example 7

`aria-live` property with invalid token value

```html
<div role="main" aria-live="nope"></div>
```

#### Failed Example 8

Element with invalid token list value

```html
<div role="alert" aria-relevant="always"></div>
```

#### Failed Example 9

`aria-expanded` state with invalid true/false/undefined value for custom element

```html
<my-button role="button" aria-expanded="collapsed">My button</my-button>
```

#### Failed Example 10

`aria-controls`, which is a required property for the role `scrollbar`, references an element that does not exist in the same document tree.
The `aria-relevant` [attribute value][] has the two tokens `text` and `always`. The `always` token is not valid for the `aria-relevant` `token list`. In order to be a valid value, all tokens must be valid.

```html
<div
role="scrollbar"
aria-controls="content1"
aria-orientation="vertical"
aria-valuemax="100"
aria-valuemin="0"
aria-valuenow="25"
></div>
<div role="alert" aria-relevant="text always"></div>
```

### Inapplicable
Expand All @@ -272,23 +227,22 @@ Element has ARIA role, but no ARIA states or properties

#### Inapplicable Example 3

`aria-checked` state with empty value

**Note**: The HTML validator flags an `aria-checked` attribute with an empty value as an issue. However, since WAI-ARIA 1.1, `aria-checked` has a default value of `undefined`.
The `aria-live` attribute does not have a value.

```html
<div role="checkbox" aria-checked>Accept terms and conditions</div>
<div role="alert" aria-live>Remember to be awesome!</div>
```

#### Inapplicable Example 4

`aria-hidden` state on an element that is not an [HTML or SVG element][].
The `aria-hidden` attribute is not on an [HTML or SVG element][].

```xml
<math aria-hidden="true"></math>
<math aria-hidden="false"></math>
```

[wai-aria specifications]: #wai-aria-specifications 'List of WAI-ARIA Specifications'
[html or svg element]: #namespaced-element
[sc131]: https://www.w3.org/TR/WCAG21/#info-and-relationships
[sc412]: https://www.w3.org/TR/WCAG21/#name-role-value
[value type]: https://www.w3.org/TR/wai-aria-1.2/#propcharacteristic_value
[wai-aria state or property]: https://www.w3.org/TR/wai-aria-1.2/#state_prop_def