From 392e15bc5b07dafeb8bc2cef559c095019fdf0d5 Mon Sep 17 00:00:00 2001 From: Jean-Yves Moyen Date: Thu, 18 Apr 2024 14:23:20 +0200 Subject: [PATCH] Extract UA controlled rule --- __tests__/spelling-ignore.yml | 3 +- _rules/target-size-ua-control-vcup8d.md | 136 ++++++++++++++++++ .../can-be-targeted-by-pointer-event.md | 36 +++++ pages/glossary/user-agent-controlled.md | 31 ++++ test-assets/target-size/shared-styles.css | 23 +++ 5 files changed, 228 insertions(+), 1 deletion(-) create mode 100644 _rules/target-size-ua-control-vcup8d.md create mode 100644 pages/glossary/can-be-targeted-by-pointer-event.md create mode 100644 pages/glossary/user-agent-controlled.md create mode 100644 test-assets/target-size/shared-styles.css diff --git a/__tests__/spelling-ignore.yml b/__tests__/spelling-ignore.yml index c8a08a3940..d5a7adadde 100644 --- a/__tests__/spelling-ignore.yml +++ b/__tests__/spelling-ignore.yml @@ -135,7 +135,7 @@ - ozplayer - GitHub -# Test case anamolies +# Test case anomalies - brewitt-taylor - level2-frame1 - level1-frame2 @@ -237,6 +237,7 @@ - focusability - unitless - luminance +- checkboxes # this seems to be the correct plural - disambiguated # Parts of Unicode diff --git a/_rules/target-size-ua-control-vcup8d.md b/_rules/target-size-ua-control-vcup8d.md new file mode 100644 index 0000000000..315832c248 --- /dev/null +++ b/_rules/target-size-ua-control-vcup8d.md @@ -0,0 +1,136 @@ +--- +id: vcup8d +name: Interactive component has size controlled by User Agent +rule_type: atomic +description: | + This rule checks that elements that can receive pointer events have a size controlled by the user agent. +accessibility_requirements: + wcag21:2.5.5: # Target size (enhanced) (AAA) + secondary: 'This success criterion is **less strict** than this rule. This is because the rule does not consider the size of the elements. Some of the failed examples may satisfy this success criterion.' + wcag22:2.5.8: # Target Size (Minimum) (AA) + secondary: 'This success criterion is **less strict** than this rule. This is because this criterion has a lower size requirement. Some of the failed examples may satisfy this success criterion.' +input_aspects: + - DOM Tree + - CSS Styling +acknowledgments: + authors: + - Jean-Yves Moyen +--- + +## Applicability + +This rule applies to any [HTML element][namespaced element] which [can be targeted by a pointer event][]. + +## Expectation + +Each test target is a [User Agent controlled component][]. + +## Assumptions + +- This rule assumes that [focusable][] `widget` are effectively clickable. If a widget is [focusable][] without being clickable, it may fail this rule while [Success Criterion 2.5.5 Target Size (enhanced)][sc255] and [Success Criterion 2.5.8 Target Size (minimum)][sc258] are satisfied. + +## Accessibility Support + +Hit testing isn't properly defined, and this has been an [issue in the CSS specification](https://github.com/w3c/csswg-drafts/issues/2325) for years. Therefore, different User Agents may perform it differently, resulting in different [clickable areas][clickable area] for the same element. As of February 2024, the ACT rules Community Group is not aware of actual cases resulting in significantly different [clickable areas][clickable area]. + +## Background + +### Bibliography + +- [Understanding Success Criterion 2.5.5: Target Size (enhanced)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-enhanced.html) +- [Understanding Success Criterion 2.5.8: Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html) + +## Test Cases + +### Passed + +#### Passed Example 1 + +This checkbox is an [User Agent controlled component][]. + +```html +

+ + I agree with the terms and conditions. +

+``` + +### Failed + +#### Failed Example 1 + +These radio buttons have their size modified by the author and are therefore not [User Agent controlled components][user agent controlled component]. Their [clickable area][] is too small. + +```html + +
+ Pick a color (required) + + +
+``` + +#### Failed Example 2 + +This `button` is not a [User Agent controlled component][]. + +```html + + +``` + +### Inapplicable + +#### Inapplicable Example 1 + +These `input` elements and `button` are `disabled` and therefore not [focusable][]. + +```html +
+
+
+ +
+``` + +#### Inapplicable Example 2 + +This button cannot be [targeted by a pointer event][] because it is entirely covered by the `div` element with a dashed red border. + +```html + + Inapplicable Example + + + + + + +
+ +``` + +[can be targeted by a pointer event]: #can-be-targeted-by-pointer-event 'Definition of Can be Targeted by a Pointer Event' +[focusable]: #focusable 'Definition of Focusable' +[namespaced element]: #namespaced-element 'Definition of Namespaced Element' +[sc255]: https://www.w3.org/TR/WCAG22/#target-size-enhanced 'Success Criterion 2.5.5 Target Size (enhanced)' +[sc258]: https://www.w3.org/TR/WCAG22/#target-size-minimum 'Success Criterion 2.5.8 Target Size (minimum)' +[targeted by a pointer event]: #can-be-targeted-by-pointer-event 'Definition of Can be Targeted by a Pointer Event' +[user agent controlled component]: #user-agent-controlled-component 'Definition of UI Controlled Component' diff --git a/pages/glossary/can-be-targeted-by-pointer-event.md b/pages/glossary/can-be-targeted-by-pointer-event.md new file mode 100644 index 0000000000..4a5a8c0168 --- /dev/null +++ b/pages/glossary/can-be-targeted-by-pointer-event.md @@ -0,0 +1,36 @@ +--- +title: Can be target by a pointer event +key: can-be-targeted-by-pointer-event +unambiguous: true +objective: true +input_aspects: + - CSS styling + - DOM tree +--- + +An element _can be targeted by pointer events_ when all the following conditions are true: + +- the element is a [semantic `widget`][semantic role]; and +- the element is [focusable][]; and +- the element [computed value][] of the `pointer-events` CSS property is `auto`; and +- through scrolling, it is possible to have parts of the element's [border box][] which intersect the viewport and are not entirely covered by the [border boxes][] of elements with greater [computed][computed value] `z-index` and a [computed][computed value] `pointer-events` of `auto`. + +#### Background + +This definition tries to capture which HTML elements can actually react to pointer events. It is not possible to have an exact definition of these for two main reasons: + +- Sometimes, the element that handles the event is not the element that appear to react to it, but an ancestor (or descendant) capturing the event during propagation or bubbling. In the most extreme case, the `body` element of a page could be the only one with an event handler, acting differently depending on where the event actually occurred. In such a case, a button would be perceived by users as something that can be targeted by a pointer event, while technically it is the `body` element which is targeted. +- It is not possible to query the list of event listeners on a given elements. Some User Agents offer way to monitor events fired at a given element, but none offer a way to query for event listeners. Additionally, an event listener might ultimately do nothing and thus, for users, the corresponding element wouldn't look like it can be targeted by pointer events (since it effectively wouldn't react to them). + +As a consequence, this definition has these two known limitations: + +- Not all HTML elements that can actually be targeted by a pointer event match this definition. For example, an author may build custom buttons without giving them an appropriate role or making them [focusable][]; or content overflowing the [border box][] of an element is clickable, but that element might not match the definition if the [border box][] is off-screen. Elements that can actually be targeted by pointer events but do not match this definition likely fail either [Success Criterion 4.1.2 Name, Role, Value][sc412] or [Success Criterion 2.1.1 Keyboard][sc211]. +- Not all HTML elements that match this definition can actually be targeted by a pointer event. For example, when the actual clickable area does not cover the full [border box][] and is entirely covered by other elements, or when the element has an event handler that does nothing. Elements that match this definition but cannot actually be targeted by pointer events likely fail [Success Criterion 2.5.6 Concurrent Input Mechanisms][sc256]. + +[border box]: https://www.w3.org/TR/css-box-3/#border-box 'CSS definition of Border Box' +[computed value]: https://www.w3.org/TR/css-cascade-3/#computed 'CSS definition of Computed Value' +[focusable]: #focusable 'Definition of Focusable' +[sc211]: https://www.w3.org/TR/WCAG22/#keyboard 'Success Criterion 2.1.1 Keyboard' +[sc256]: https://www.w3.org/TR/WCAG22/#concurrent-input-mechanisms 'Success Criterion 2.5.6 Concurrent Input Mechanisms' +[sc412]: https://www.w3.org/TR/WCAG22/#name-role-value 'Success Criterion 4.1.2 Name, Role, Value' +[semantic role]: #semantic-role 'Definition of Semantic Role' diff --git a/pages/glossary/user-agent-controlled.md b/pages/glossary/user-agent-controlled.md new file mode 100644 index 0000000000..1cadad0a1e --- /dev/null +++ b/pages/glossary/user-agent-controlled.md @@ -0,0 +1,31 @@ +--- +title: User-Agent Controlled Component +key: user-agent-controlled-component +unambiguous: true +objective: true +input_aspects: + - CSS styling + - DOM tree +--- + +A _User-Agent Controlled Component_ is an [HTML element][namespace element] for which all the following are true: + +- the element has an [implicit role][] which is a [semantic `widget`][semantic role]; and +- the [computed values][] of the element's `height` and `width` CSS properties do not depend on content provided by the author; and +- the [computed values][] of the element's `height` and `width` CSS properties do not depend on any CSS property with a [cascaded value][] with "Author" [origin][]. + +#### Examples + +Typically, radio buttons or checkboxes are User-Agent controlled, until an author does change their dimensions. + +Links and buttons usually aren't, because their (text) content is provided by the author and the width depends on it. + +Days in a calendar widget build with an `` element are also User-Agent controlled since their content isn't provided by the author and their dimension do not depend on values provided by the author. + +Directly setting the `height` or `width` CSS properties makes an element not User-Agent controlled. Changing the `max-height` or `min-width` properties can make it not User-Agent controlled, if the added constraint impacts the [computed][computed values] `height` or `width` properties (i.e., if the `height` would be larger than `max-height` and is restricted by it; or if the `width` would be smaller than `min-width` and is changed by it). + +[cascaded value]: https://www.w3.org/TR/css-cascade-5/#cascade-value 'CSS definition of computed value' +[computed values]: https://www.w3.org/TR/css-cascade-3/#computed 'CSS definition of Computed Value' +[implicit role]: #implicit-role 'Definition of Implicit Role' +[origin]: https://drafts.csswg.org/css-cascade-5/#cascading-origins 'CSS definition of Cascading Origin' +[semantic role]: #semantic-role 'Definition of Semantic Role' diff --git a/test-assets/target-size/shared-styles.css b/test-assets/target-size/shared-styles.css new file mode 100644 index 0000000000..947ef0bc90 --- /dev/null +++ b/test-assets/target-size/shared-styles.css @@ -0,0 +1,23 @@ +.highlight { + position: absolute; + z-index: 0; +} + +.good { + border: green solid 1px; +} +.bad { + border: red dashed 1px; +} + +.highlightable { + position: relative; + z-index: 5; +} + +.placeholder { + background-color: transparent; + border: dashed 2px black; + padding: 0; + position: absolute; +}