From 02fee233c1eb2981d337c539c922aba017a8ed84 Mon Sep 17 00:00:00 2001 From: Domenic Denicola Date: Fri, 18 Sep 2020 13:34:32 -0400 Subject: [PATCH] Generalize AccessibilityRole/AriaAttributes IDL (#984) * Generalize AccessibilityRole/AriaAttributes IDL This generalizes the AccessibilityRole/AriaAttributes IDL mixins to allow them to have different behaviors per host interface. For Element, they have the reflection behavior specified, but e.g. for ElementInternals, HTML can use this framework to define different behavior. In the process, this consolidates the two mixins into one ("ARIAMixin"), since this makes it easier to define their behavior uniformly, and consumers should generally not mix in one without the other. --- index.html | 199 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 118 insertions(+), 81 deletions(-) diff --git a/index.html b/index.html index ff0c55173..d34106213 100644 --- a/index.html +++ b/index.html @@ -362,7 +362,7 @@

Information for Authors

User agents that support WAI-ARIA expand the usage of host language mechanisms such as tabindex, focus, and blur to allow them on all elements. Where the host language supports it, authors MAY add any element such as a div, span, or img to the default tab order by setting tabindex="0". In addition, any item with tabindex equal to a negative integer is focusable via script or a mouse click, but is not part of the default tab order. This is supported in both [[HTML]] and [[SVG2]].

Authors MAY use aria-activedescendant to inform assistive technologies which descendant of a widget element is treated as having keyboard focus in the user interface if the role of the widget element supports aria-activedescendant. - This is often a more convenient way of providing keyboard navigation within widgets, such as a listbox, where the widget occupies only one stop in the page Tab sequence and other keys, typically arrow keys, are used to focus elements inside the widget. + This is often a more convenient way of providing keyboard navigation within widgets, such as a listbox, where the widget occupies only one stop in the page Tab sequence and other keys, typically arrow keys, are used to focus elements inside the widget.

Typically, the author will use host language semantics to put the widget in the Tab sequence (e.g., tabindex="0" in HTML) and aria-activedescendant to point to the ID of the currently active descendant. The author, not the user agent, is responsible for styling the currently active descendant to show it has keyboard focus. The author cannot use :focus to style the currently active descendant since the actual focus is on the container.

More information on managing focus can be found in the Developing a Keyboard Interface section of the WAI-ARIA Authoring Practices.

@@ -2208,7 +2208,7 @@

Definition of Roles

Supported States and Properties: - + - + Name From: prohibited @@ -11397,7 +11397,7 @@

Definitions of States and Properties (all aria-* attributes)

Inherits into Roles: Placeholder - + Value: ID reference @@ -11568,8 +11568,8 @@

Definitions of States and Properties (all aria-* attributes)

The aria-haspopup property is an enumerated type. User agents MUST treat any value of aria-haspopup that is not included in the list of allowed values, including an empty string, as if the value false had been provided. To provide backward compatibility with ARIA 1.0 content, user agents MUST treat an aria-haspopup value of true as equivalent to a value of menu.

Assistive technologies SHOULD NOT expose the aria-haspopup property if it has a value of false.

A tooltip is not considered to be a popup in this context.

-

aria-haspopup is most relevant to use when there is a visual indicator in the element that triggers the popup. - For example, many controls styled with a downward pointing triangle, chevron, or ellipsis (three consecutive dots) have become standard visual indicators that a popup will display when the control is activated. +

aria-haspopup is most relevant to use when there is a visual indicator in the element that triggers the popup. + For example, many controls styled with a downward pointing triangle, chevron, or ellipsis (three consecutive dots) have become standard visual indicators that a popup will display when the control is activated. If some functional difference is relevant to display to a sighted user by means of a different visual style, that functional difference is usually relevant to convey to users of assistive technology. If there is no visual indication that an element will trigger a popup, authors are advised to consider whether use of aria-haspopup is necessary, and avoid using it when it's not.

@@ -13538,22 +13538,13 @@

States and Properties

IDL Interface

-

Conforming user agents MUST implement the following IDL interfaces.

-
-

Interface Mixin AccessibilityRole

+

Conforming user agents MUST implement the following IDL interface.

+
+

Interface Mixin ARIAMixin

-			interface mixin AccessibilityRole {
-				attribute DOMString role;
-			};
-			Element includes AccessibilityRole;
-
-

User agents MUST reflect the role content attribute as the role IDL attribute.

-
+ interface mixin ARIAMixin { + attribute DOMString? role; -
-

Interface Mixin AriaAttributes

- 
-			interface mixin AriaAttributes {
 				
 				attribute DOMString ariaAtomic;
 				attribute DOMString ariaAutoComplete;
@@ -13604,65 +13595,93 @@ 
Interface Mixin AriaAttributes

 				attribute DOMString ariaValueNow;
 				attribute DOMString ariaValueText;
 			};
-			Element includes AriaAttributes;
-
-

ARIA Attribute Reflection

-

User agents MUST reflect the following content attributes to each of the corresponding IDL attributes.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
IDL AttributeReflected ARIA Content Attribute
ariaAtomicaria-atomic
ariaAutoCompletearia-autocomplete
ariaBusyaria-busy
ariaCheckedaria-checked
ariaColCountaria-colcount
ariaColIndexaria-colindex
ariaColIndexTextaria-colindextext
ariaColSpanaria-colspan
ariaCurrentaria-current
ariaDescriptionaria-description
ariaDisabledaria-disabled
ariaExpandedaria-expanded
ariaHasPopuparia-haspopup
ariaHiddenaria-hidden
ariaInvalidaria-invalid
ariaKeyShortcutsaria-keyshortcuts
ariaLabelaria-label
ariaLevelaria-level
ariaLivearia-live
ariaModalaria-modal
ariaMultiLinearia-multiline
ariaMultiSelectablearia-multiselectable
ariaOrientationaria-orientation
ariaPlaceholderaria-placeholder
ariaPosInSetaria-posinset
ariaPressedaria-pressed
ariaReadOnlyaria-readonly
ariaRequiredaria-required
ariaRoleDescriptionaria-roledescription
ariaRowCountaria-rowcount
ariaRowIndexaria-rowindex
ariaRowIndexTextaria-rowindextext
ariaRowSpanaria-rowspan
ariaSelectedaria-selected
ariaSetSizearia-setsize
ariaSortaria-sort
ariaValueMaxaria-valuemax
ariaValueMinaria-valuemin
ariaValueNowaria-valuenow
ariaValueTextaria-valuetext
-

Note: Attributes aria-dropeffect and aria-grabbed were deprecated in ARIA 1.1 and do not have corresponding IDL attributes.

-
+ +

Interfaces that include ARIAMixin must provide the following algorithms:

+ +
    +
  • ARIAMixin getter steps, which take the host interface instance, IDL attribute name, and content attribute name, and must return a string value; and +
  • ARIAMixin setter steps, which take the host interface instance, IDL attribute name, content attribute name, and string value, and must return nothing.
    • +
+ +

For every IDL attribute idlAttribute defined in ARIAMixin, on getting, it must perform the following steps:

+ +
    +

  1. Let contentAttribute be the ARIA content attribute determined by looking up idlAttribute in the ARIA Attribute Correspondence table.

    2. + +

  2. Return the result of running the ARIAMixin getter steps, given this, idlAttribute, and contentAttribute.

    3. +
+ +

Similarly, on setting, it must perform the following steps:

+ +
    +

  1. Let contentAttribute be the ARIA content attribute determined by looking up idlAttribute in the ARIA Attribute Correspondence table.

    2. + +

  2. Run the ARIAMixin setter steps, given this, idlAttribute, contentAttribute, and the given value.

    3. +
+ +

This very general framework is motivated by the desire for different host interfaces, such as Element and ElementInternals, to give these IDL attributes different behaviors. The alternative is requiring each host interface to duplicate the IDL attributes independently, so that they can specify independent behaviors, but that comes with a high risk of them getting out of sync.

+
+ +
+

ARIA Attribute Correspondence

+

The following table provides a correspondence between IDL attribute names and content attribute names, for use by ARIAMixin.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
IDL AttributeReflected ARIA Content Attribute
rolerole
ariaAtomicaria-atomic
ariaAutoCompletearia-autocomplete
ariaBusyaria-busy
ariaCheckedaria-checked
ariaColCountaria-colcount
ariaColIndexaria-colindex
ariaColIndexTextaria-colindextext
ariaColSpanaria-colspan
ariaCurrentaria-current
ariaDescriptionaria-description
ariaDisabledaria-disabled
ariaExpandedaria-expanded
ariaHasPopuparia-haspopup
ariaHiddenaria-hidden
ariaInvalidaria-invalid
ariaKeyShortcutsaria-keyshortcuts
ariaLabelaria-label
ariaLevelaria-level
ariaLivearia-live
ariaModalaria-modal
ariaMultiLinearia-multiline
ariaMultiSelectablearia-multiselectable
ariaOrientationaria-orientation
ariaPlaceholderaria-placeholder
ariaPosInSetaria-posinset
ariaPressedaria-pressed
ariaReadOnlyaria-readonly
ariaRequiredaria-required
ariaRoleDescriptionaria-roledescription
ariaRowCountaria-rowcount
ariaRowIndexaria-rowindex
ariaRowIndexTextaria-rowindextext
ariaRowSpanaria-rowspan
ariaSelectedaria-selected
ariaSetSizearia-setsize
ariaSortaria-sort
ariaValueMaxaria-valuemax
ariaValueMinaria-valuemin
ariaValueNowaria-valuenow
ariaValueTextaria-valuetext
+

Note: Attributes aria-dropeffect and aria-grabbed were deprecated in ARIA 1.1 and do not have corresponding IDL attributes.

+

Disambiguation Pattern

Though specification authors may make exceptions to this pattern, the following rules were used to disambiguate names and case of the IDL attributes listed above.

@@ -13683,6 +13702,24 @@

IDL Attribute Name Notes or Exceptions

+
+

ARIAMixin Mixed in to Element

+ +

User agents MUST include ARIAMixin on Element:

+ + 
+			Element includes ARIAMixin;
+
+ +

For Element:

+
    +

  • The ARIAMixin getter steps given element, idlAttribute, and contentAttribute are to return the result of the getter algorithm for idlAttribute reflecting contentAttribute on element.

    • +

  • The ARIAMixin setter steps given element, idlAttribute, contentAttribute, and value are to perform the setter algorithm for idlAttribute reflecting contentAttribute on element, given value.

    • +
+ +

In practice, this means that, e.g., the role IDL on Element reflects the role content attribute; the ariaValueMin IDL attribute reflects the aria-valuemin content attribute; etc.

+
+

Example IDL Attribute Usage

The primary purpose of ARIA IDL attribute reflection is to ease JavaScript-based manipulation of values. The following examples demonstrate its usage.

@@ -13826,8 +13863,8 @@

Substantive changes since the last public working draft

  • 11-Oct-2019: Remove allowance of group in list
  • 09-Oct-2019: Add missing implicit value for progressbar
  • 09-Oct-2019: Remove accessible name required from log and timer
    • -
  • 22-Aug-2019: Remove aria-level from grid
    • -
  • 23-Jul-2019: Add generic role
    • +
  • 22-Aug-2019: Remove aria-level from grid
    • +
  • 23-Jul-2019: Add generic role
  • 11-Jul-2019: Remove advice against changing roles
  • 11-Jul-2019: Set Accessible Name Required to false on gridcell
  • 11-Jul-2019: Add associationlist, associationlistitemkey, and associationlistitemvalue roles