Add definition for implicit/explicit ARIA attributes

.github/ISSUE_TEMPLATE/rules-issue-template.md

@@ -4,10 +4,7 @@ about: issues related with ACT Rules
 title: ''
 labels: ''
 assignees: ''
-
----
-
-Please describe the issue with references and relevant examples where necessary.
+---Please describe the issue with references and relevant examples where necessary.
 
 --- or ---
 

__tests__/spelling.js

@@ -109,7 +109,9 @@ function getCuratedMarkdownBody(body, options = {}) {
  * @returns {String[]}
  */
 function getSpellIgnored() {
-	const ignoreConfigured = yaml.safeLoad(fs.readFileSync('./__tests__/spelling-ignore.yml', 'utf8'), {schema: yaml.FAILSAFE_SCHEMA}) //added schema due to entries starting with a non-zero digit
+	const ignoreConfigured = yaml.safeLoad(fs.readFileSync('./__tests__/spelling-ignore.yml', 'utf8'), {
+		schema: yaml.FAILSAFE_SCHEMA,
+	}) //added schema due to entries starting with a non-zero digit
 
 	/*
 	Building spelling exception in the shape FOOxxx where xxx is a number.

_rules/aria-state-or-property-permitted-5c01ea.md

@@ -37,7 +37,7 @@ acknowledgments:
 
 ## Applicability
 
-This rule applies to any [WAI-ARIA state or property][] that is specified on an [HTML or SVG element][namespaced element] that is [included in the accessibility tree][].
+This rule applies to any [WAI-ARIA state or property][] that is [explicitly set][aria set explicit] on an [HTML or SVG element][namespaced element] that is [included in the accessibility tree][].
 
 ## Expectation 1
 
@@ -57,6 +57,8 @@ The presence of prohibited ARIA attributes is often the result of a developer us
 
 In HTML, there are language features that do not have corresponding implicit WAI-ARIA semantics. As per [ARIA in HTML](https://www.w3.org/TR/html-aria/), those elements can have [global states or properties][global]. Some of those elements can also have [inherited][], [supported][], or [required][] [states][state] or [properties][property] that correspond to a [WAI-ARIA role](https://www.w3.org/TR/wai-aria-1.2/#introroles). For example, the `audio` element has no corresponding ARIA semantics but it can have [inherited][], [supported][], or [required][] [states][state] or [properties][property] of the [`application` role](https://www.w3.org/TR/wai-aria-1.2/#application).
 
+This rule only applies to [explicitly set][aria set explicit] attributes since these have been provided by authors and using the wrong one is therefore an author issue. If an [implicitly set][aria set implicit] attribute is incorrect, this is not necessarily an author error, e.g., it can be the result of re-purposing an existing element.
+
 Assessing the value of the attribute is out of scope for this rule.
 
 ### Assumptions
@@ -218,7 +220,18 @@ This `div` element is not [included in the accessibility tree][], hence its [WAI
 <div role="button" aria-sort="" style="display:none;"></div>
 ```
 
+#### Inapplicable Example 3
+
+This `button` does not have any [explicitly set][aria set explicit] ARIA attribute. It has an [implicitly set][aria set implicit] `aria-checked` state, due to the [absence of a `checked` attribute][checked absent] on the `input` element with a `type` [attribute value][] of `checkbox`.
+
+```html
+<input type="checkbox" role="button" />
+```
+
+[aria set explicit]: #aria-attribute-set:explicit 'Definition of ARIA Attribute Set Explicitly'
+[aria set implicit]: #aria-attribute-set:implicit 'Definition of ARIA Attribute Set Implicitly'
 [attribute value]: #attribute-value 'Definition of attribute value'
+[checked absent]: https://www.w3.org/TR/html-aam-1.0/#att-checked-absent 'HTML Accessibility API Mappings, Attribute Checked absent'
 [explicit role]: #explicit-role 'Definition of Explicit Role'
 [focusable]: #focusable 'Definition of focusable'
 [global]: https://www.w3.org/TR/wai-aria-1.2/#global_states 'Definition of Global ARIA States and Properties'

_rules/focusable-no-keyboard-trap-standard-nav-a1b64e.md

@@ -88,43 +88,43 @@ use [standard keyboard navigation](#standard-keyboard-navigation) using the Esca
 ```html
 <div>Main page content with <a href="#">some link</a></div>
 <div aria-hidden="true">
-    <a href="#" id="sentinelBefore" style="position:absolute; top:-999em"
-        >Upon receiving focus, this focus sentinel should wrap focus to the bottom of the modal</a
-    >
+	<a href="#" id="sentinelBefore" style="position:absolute; top:-999em"
+		>Upon receiving focus, this focus sentinel should wrap focus to the bottom of the modal</a
+	>
 </div>
 <div
-    id="sampleModal"
-    role="dialog"
-    aria-label="Sample Modal"
-    aria-modal="true"
-    style="border: solid black 1px; padding: 1rem;"
+	id="sampleModal"
+	role="dialog"
+	aria-label="Sample Modal"
+	aria-modal="true"
+	style="border: solid black 1px; padding: 1rem;"
 >
-    <label>First and last name <input id="dialogFirst"/></label><br />
-    <button id="closeButton">Close button</button>
+	<label>First and last name <input id="dialogFirst"/></label><br />
+	<button id="closeButton">Close button</button>
 </div>
 <div aria-hidden="true">
-    <a href="#" id="sentinelAfter" style="position:absolute; top:-999em"
-        >Upon receiving focus, this focus sentinel should wrap focus to the top of the modal</a
-    >
+	<a href="#" id="sentinelAfter" style="position:absolute; top:-999em"
+		>Upon receiving focus, this focus sentinel should wrap focus to the top of the modal</a
+	>
 </div>
 <script>
-    window.addEventListener('load', () => {
-        document.getElementById('dialogFirst').focus();
-    })
-    document.getElementById('sentinelBefore').addEventListener('focus', () => {
-        document.getElementById('closeButton').focus()
-    })
-    document.getElementById('sentinelAfter').addEventListener('focus', () => {
-        document.getElementById('dialogFirst').focus()
-    })
-    document.getElementById('closeButton').addEventListener('click', () => {
-        document.getElementById('sampleModal').style.display = 'none'
-    })
-    document.getElementById('sampleModal').addEventListener('keydown', (evt) => {
-        if (evt.key === "Escape") {
-            document.getElementById('sampleModal').style.display = 'none';    
-        }
-    })
+	window.addEventListener('load', () => {
+		document.getElementById('dialogFirst').focus()
+	})
+	document.getElementById('sentinelBefore').addEventListener('focus', () => {
+		document.getElementById('closeButton').focus()
+	})
+	document.getElementById('sentinelAfter').addEventListener('focus', () => {
+		document.getElementById('dialogFirst').focus()
+	})
+	document.getElementById('closeButton').addEventListener('click', () => {
+		document.getElementById('sampleModal').style.display = 'none'
+	})
+	document.getElementById('sampleModal').addEventListener('keydown', evt => {
+		if (evt.key === 'Escape') {
+			document.getElementById('sampleModal').style.display = 'none'
+		}
+	})
 </script>
 ```
 

_rules/role-attribute-valid-value-674b10.md

@@ -49,6 +49,8 @@ The `role` attribute is a set of [space separated tokens][]. Having a [whitespac
 
 Not every role can be used on every element. Which ARIA roles may be used on which HTML elements is defined in [ARIA in HTML](https://www.w3.org/TR/html-aria/). Testing this is not part of this rule.
 
+This rule considers the [value of the attribute as set in the HTML code][html attribute value], which differs from the [attribute value][attribute value] obtained after parsing it and discarding invalid tokens.
+
 ### Assumptions
 
 There are no assumptions.
@@ -179,7 +181,9 @@ This `role` attribute is specified on an element which is [programmatically hidd
 ```
 
 [ascii whitespace]: https://infra.spec.whatwg.org/#ascii-whitespace 'Definition of ASCII whitespace'
+[attribute value]: #attribute-value:role 'Definition of Attribute Value of the Role Attribute'
 [html or svg element]: #namespaced-element
+[html attribute value]: https://html.spec.whatwg.org/multipage/dom.html#attributes 'HTML Specification of Attribute Value'
 [implicit role]: #implicit-role 'Definition of Implicit Role'
 [programmatically hidden]: #programmatically-hidden 'Definition of Programmatically Hidden'
 [role attribute]: https://www.w3.org/TR/role-attribute/ 'Specification of the Role attribute'

_rules/role-required-states-and-properties-4e8ab6.md

@@ -32,17 +32,19 @@ acknowledgments:
 
 ## Applicability
 
-This rule applies to any [HTML or SVG element][] that is [included in the accessibility tree][] and has an [explicit semantic role][], except if the element has an [implicit semantic role][] that is identical to the [explicit semantic role][].
+This rule applies to any [HTML or SVG element][] that is [included in the accessibility tree][].
 
 ## Expectation
 
-For each test target, the [WAI-ARIA required states and properties][] for the role are set and not empty (`""`), unless the state or property has a default value listed under [WAI-ARIA implicit value for role][].
+For each test target, the [WAI-ARIA required states and properties][] for the role are [set][aria set] and not empty (`""`).
+
+The attributes may be [explicitly set][aria set explicit], [implicitly set][aria set implicit], or [set by default][aria set default].
 
 ## Background
 
 Omitting [WAI-ARIA required states and properties][] is often the result of a developer error. When required properties are missing and a default value is not specified by [WAI-ARIA Specifications][], the behavior is not defined. For [WAI-ARIA 1.2][], the only [explicit semantic roles][explicit semantic role] with a required property with a default value are the `option` and `tabs roles` for the `aria-selected` property.
 
-This rule is testing author built components that specify [explicit semantic roles][explicit semantic role] and not components that keep their [implicit semantic role][]. For components that keep their [implicit semantic role][], all native HTML and SVG elements have native attributes that are mapped to all of the [WAI-ARIA required states and properties](https://www.w3.org/TR/wai-aria/#requiredState). Most of these mappings are defined in the [HTML Accessibility API Mappings, Attribute State and Property Mappings][html aam].
+The way the attribute is [set][aria set] doesn't matter for this rule. As long as authors can rely on User Agents or Assistive Technologies to set the attribute, this won't create problems for users. As per the [First Rule of ARIA use][], authors should rely on [implicitly set][aria set implicit] attributes when possible.
 
 ### Assumptions
 
@@ -66,7 +68,7 @@ This rule relies on browsers and assistive technologies to support leaving out [
 
 #### Passed Example 1
 
-This `heading` has the required `aria-level` property.
+This `heading` has the required `aria-level` property [explicitly set][aria set explicit].
 
 ```html
 <div role="heading" aria-level="1">
@@ -76,7 +78,7 @@ This `heading` has the required `aria-level` property.
 
 #### Passed Example 2
 
-This `checkbox` has the required `aria-checked` property.
+This `checkbox` has the required `aria-checked` property [explicitly set][aria set explicit].
 
 ```html
 <div role="checkbox" aria-checked="false" aria-labelledby="label"></div>
@@ -85,7 +87,7 @@ This `checkbox` has the required `aria-checked` property.
 
 #### Passed Example 3
 
-This `scrollbar` has the required properties `aria-controls` and `aria-valuenow`. `aria-valuemin` has a default value of 0 and `aria-valuemax` of 100.
+This `scrollbar` has the required properties `aria-controls` and `aria-valuenow` [explicitly set][aria set explicit]. `aria-valuemin` has a default value of 0 and `aria-valuemax` of 100 and are thus [set by default][aria set default].
 
 ```html
 <div role="scrollbar" aria-controls="content" aria-valuenow="0"></div>
@@ -94,7 +96,7 @@ This `scrollbar` has the required properties `aria-controls` and `aria-valuenow`
 
 #### Passed Example 4
 
-These `option` nodes do not need the required `aria-selected` property because it has a default value of `false`.
+These `option` nodes have the required `aria-selected` property [set by default][aria set default].
 
 ```html
 <div id="label">Tags</div>
@@ -106,7 +108,7 @@ These `option` nodes do not need the required `aria-selected` property because i
 
 #### Passed Example 5
 
-This `separator` is not a `widget` because it is not [focusable][]. The `separator` role only requires the `aria-valuenow` property when the element is focusable.
+This `separator` is not a `widget` because it is not [focusable][]. The `separator` role does not have any required property when the element is not focusable.
 
 ```html
 <p>My first HTML</p>
@@ -116,7 +118,7 @@ This `separator` is not a `widget` because it is not [focusable][]. The `separat
 
 #### Passed Example 6
 
-This `combobox` has the required properties `aria-controls` and `aria-expanded`.
+This `combobox` has the required properties `aria-controls` and `aria-expanded` [explicitly set][aria set explicit].
 
 ```html
 <label for="tag_combo">Tag</label>
@@ -127,11 +129,41 @@ This `combobox` has the required properties `aria-controls` and `aria-expanded`.
 </ul>
 ```
 
+#### Passed Example 7
+
+This `checkbox` has its required `aria-checked` property [implicitly set][aria set implicit].
+
+```html
+<label>
+	<input type="checkbox" />
+	Check me
+</label>
+```
+
+#### Passed Example 8
+
+This `menuitemcheckbox` has its required `aria-checked` property [implicitly set][aria set implicit].
+
+```html
+<label>
+	<input type="checkbox" role="menuitemcheckbox" />
+	Check me
+</label>
+```
+
+#### Passed Example 9
+
+This `iframe` element is [included in the accessibility tree][], even without a role, and therefore has no [WAI-ARIA required states and properties][].
+
+```html
+<iframe srcdoc="<div>ACT rules are awesome!</div>" title="ACT rules" />
+```
+
 ### Failed
 
 #### Failed Example 1
 
-This `heading` does not have the required `aria-level` property. Prior to [WAI-ARIA 1.2][] the `heading` role had an implicit default `aria-level` value of `2`. As of WAI-ARIA 1.2 this property must be explicitly set.
+This `heading` does not have the required `aria-level` property. Prior to [WAI-ARIA 1.2][] the `heading` role had a default `aria-level` value of `2`. As of WAI-ARIA 1.2 this property must be [explicitly set][aria set explicit].
 
 ```html
 <div role="heading">
@@ -141,7 +173,7 @@ This `heading` does not have the required `aria-level` property. Prior to [WAI-A
 
 #### Failed Example 2
 
-This `switch` does not have the required `aria-checked` property. Prior to [WAI-ARIA 1.2][] the `switch` role had an implicit default `aria-checked` value of `false`. As of WAI-ARIA 1.2 this property must be explicitly set.
+This `switch` does not have the required `aria-checked` property. Prior to [WAI-ARIA 1.2][] the `switch` role had a default `aria-checked` value of `false`. As of WAI-ARIA 1.2 this property must be [explicitly set][aria set explicit].
 
 ```html
 <div role="switch">
@@ -151,7 +183,7 @@ This `switch` does not have the required `aria-checked` property. Prior to [WAI-
 
 #### Failed Example 3
 
-This `checkbox` does not have the required property `aria-checked`. Prior to [WAI-ARIA 1.2][] the `checkbox` had an implicit default `aria-checked` value of `false`. As of WAI-ARIA 1.2 this property must be explicitly set.
+This `checkbox` does not have the required property `aria-checked`. Prior to [WAI-ARIA 1.2][] the `checkbox` role had a default `aria-checked` value of `false`. As of WAI-ARIA 1.2 this property must be [explicitly set][aria set explicit].
 
 ```html
 <div role="checkbox" aria-labelledby="label"></div>
@@ -170,7 +202,7 @@ This `separator` does not have the required `aria-valuenow` property. This is re
 
 #### Failed Example 5
 
-This `combobox` does not have the required `aria-expanded` property. Prior to [WAI-ARIA 1.2][] the `combobox` had an implicit default `aria-expanded` value of `false`. As of WAI-ARIA 1.2 this property must be explicitly set.
+This `combobox` does not have the required `aria-expanded` property. Prior to [WAI-ARIA 1.2][] the `combobox` had a default `aria-expanded` value of `false`. As of WAI-ARIA 1.2 this property must be [explicitly set][aria set explicit].
 
 ```html
 <label for="tag_combo">Tag</label>
@@ -198,31 +230,26 @@ This `combobox` uses `aria-owns` instead of using the required `aria-controls` p
 
 #### Inapplicable Example 1
 
-This `div` does not have a [semantic role](#semantic-role).
+This `div` is not [included in the accessibility tree][] due to its role of `generic`.
 
 ```html
 <div>Some Content</div>
 ```
 
 #### Inapplicable Example 2
 
-This `checkbox` has an [implicit semantic role](#implicit-role) that is identical to the [explicit semantic role](#explicit-role). This allows native HTML `checked` attribute to apply.
-
-```html
-<input type="checkbox" role="checkbox" />
-```
-
-#### Inapplicable Example 3
-
 This `combobox` is not [included in the accessibility tree][] due to its styling, hiding it from everybody.
 
 ```html
 <div role="combobox" style="display:none;"></div>
 ```
 
+[aria set]: #aria-attribute-set 'Definition of ARIA Attribute Set'
+[aria set default]: #aria-attribute-set:default 'Definition of ARIA Attribute Set by Default'
+[aria set explicit]: #aria-attribute-set:explicit 'Definition of ARIA Attribute Set Explicitly'
+[aria set implicit]: #aria-attribute-set:implicit 'Definition of ARIA Attribute Set Implicitly'
 [explicit semantic role]: #explicit-role 'Definition of explicit semantic role'
-[html aam]: https://www.w3.org/TR/html-aam-1.0/#html-attribute-state-and-property-mappings 'Specification of HTML attributes value mapping to ARIA states and properties'
-[implicit semantic role]: #implicit-role 'Definition of implicit semantic role'
+[first rule of aria use]: https://www.w3.org/TR/using-aria/#rule1 'First Rule of ARIA Use'
 [included in the accessibility tree]: #included-in-the-accessibility-tree 'Definition of Included in The Accessibility Tree'
 [wai-aria required states and properties]: https://www.w3.org/TR/wai-aria-1.2/#requiredState
 [wai-aria specifications]: #wai-aria-specifications 'Definition of WAI-ARIA Specifications'

_rules/scrollable-element-keyboard-accessible-0ssw9k.md

@@ -40,8 +40,9 @@ This rule applies to any [HTML element][] that has [visible][] [children][] in t
 
 ## Expectation
 
-For each target element, at least one of the following is true: 
-- the element is included in [sequential focus navigation][]; or 
+For each target element, at least one of the following is true:
+
+- the element is included in [sequential focus navigation][]; or
 - the element has a [descendant][] in the [flat tree][] that is included in [sequential focus navigation][]; or
 - the element is [inert][].
 
@@ -119,7 +120,7 @@ This [scrollable][] `section` element is [inert][] because of the modal dialog,
 ```html
 <style>
 	dialog:-internal-dialog-in-top-layer::backdrop {
-    		background: rgba(1, 1, 1, 0.8);
+		background: rgba(1, 1, 1, 0.8);
 	}
 </style>
 <section style="height: 100px; width: 500px; overflow: scroll;" tabindex="0">
@@ -144,11 +145,11 @@ This [scrollable][] `section` element is [inert][] because of the modal dialog,
 </dialog>
 <script>
 	const openDialog = () => {
-		ppDialog.showModal();
+		ppDialog.showModal()
 		myFrame.tabIndex = '-1'
 	}
-	ppDialog.addEventListener('close', () => myFrame.tabIndex = 0)
-	window.addEventListener('DOMContentLoaded', openDialog);
+	ppDialog.addEventListener('close', () => (myFrame.tabIndex = 0))
+	window.addEventListener('DOMContentLoaded', openDialog)
 </script>
 ```