Skip to content

ARIA state or property: various editorial improvements #2012

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

Merged
merged 13 commits into from
Apr 6, 2023
Merged

ARIA state or property: various editorial improvements #2012

Changes from 8 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: 77 additions & 63 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,29 @@ 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], except in the following instances:

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.
- <dfn id="off6ek:id-reference">ID Reference</dfn>: For `ID Reference` value types an ID referenced elements is only required for `aria-controls` with [semantic][semantic role] `scrollbar` elements, and with [semantic][semantic role] `combobox` elements that have an `aria-expanded` [attribute value][] of `true`. The ID referenced element must exist in the same [document tree][] or [shadow tree][] as the test target's element.

For value type `URI` the value matches the [generic URI syntax](https://www.ietf.org/rfc/rfc3986.txt).
- <dfn id="off6ek:id-reference-list">ID Reference List</dfn>: For `ID Reference List` value types, 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].
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.

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.

For value type `URI`, this rule does not require that the destination URI exists.
Only for [WAI-ARIA required properties][] 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, having the referenced element is optional. For example, `aria-errormessage` attribute on an `input` element may have a fixed value, but the element with the error message is only added to the page when an error actually occurred.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should expand on that to explain the combobox exception.


### Related rules

Expand All @@ -72,39 +70,47 @@ 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][]. Because `aria-errormessage` is not a required property for `textbox`, an element with a matching ID is not required.

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

#### Passed Example 6

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
<h1>Shopping list</h1>
Expand All @@ -113,43 +119,41 @@ For value type `URI`, this rule does not require that the destination URI exists
<div id="item2">Bananas</div>
```

#### Passed Example 6
#### Passed Example 7

`aria-rowindex` property with valid integer value
The `aria-rowindex` [attribute value][] of 2 is a valid `integer` [value type][].

```html
<div role="gridcell" aria-rowindex="2">Fred</div>
```

#### Passed Example 7
#### Passed Example 8

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

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

#### Passed Example 8
#### Passed Example 9

`aria-placeholder` property with valid string value
The `aria-current` [attribute value][] of `page` is a valid `token` [value type][].

```html
<div role="textbox" aria-placeholder="MM-DD-YYYY" aria-label="Your birthdate">
MM-DD-YYYY
</div>
<a href="/" aria-current="page">Home</a>
```

#### Passed Example 9
#### Passed Example 10

`aria-relevant` property with valid token list values
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 role="alert" aria-relevant="text removals"></div>
```

#### Passed Example 10
#### Passed Example 11

`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-controls` [attribute value][], 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.

```html
<div id="content1">Lorem ipsum...</div>
Expand All @@ -163,82 +167,77 @@ For value type `URI`, this rule does not require that the destination URI exists
></div>
```

#### Passed Example 12

The `aria-controls` [attribute value][] on a collapsed `combobox` does not require the ID referenced element to exist.

```html
<label>
Tag
<input role="combobox" aria-expanded="false" aria-controls="popup_listbox" />
</label>
```

### 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-expanded` [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
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="main" aria-live="nope"></div>
<div role="alert" aria-relevant="text always"></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.

```html
Expand All @@ -252,6 +251,17 @@ Element with invalid token list value
></div>
```

#### Failed Example 9

The `aria-controls` [attribute value][] on an expanded `combobox` requires the ID referenced element to exist.

```html
<label>
Tag
<input role="combobox" aria-expanded="true" aria-controls="popup_listbox" />
</label>
```

### Inapplicable

#### Inapplicable Example 1
Expand All @@ -272,7 +282,7 @@ Element has ARIA role, but no ARIA states or properties

#### Inapplicable Example 3

`aria-checked` state with empty value
The `aria-checked` attribute does not have a 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`.

Expand All @@ -282,13 +292,17 @@ Element has ARIA role, but no ARIA states or properties

#### 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
[wai-aria required properties]: https://www.w3.org/TR/wai-aria-1.2/#requiredState
[document tree]: https://dom.spec.whatwg.org/#document-trees
[shadow tree]: https://dom.spec.whatwg.org/#shadow-trees
[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