Editorial: aria-controls spec update (#1996)

resolves #995 

The intent with this update is, 4 years later, to propose a draft solution for the issue I opened.

With the progress made on aria-details, and the overlaps in how this attribute could have been useful, I did take great liberty in pulling in further explanation/examples for aria-controls from the existing aria-details spec text.

Things i didn't overly call out in this pr, but should probably make their way in there concern recommendations on whether or not to expose the controlling relationship depending on DOM/a11y API relationship.  E.g., we probably don't need an explicit user exposed controlling relationship if a controlled element is directly after the controlling element in the dom (e.g., a disclosure widget) but we _would_ want AT to know they could make this association clear if the elements were located in different portions of the a11y tree - e.g., a button opening a non-modal dialog that happens to be at the bottom of the DOM, but the button is somewhere else entirely.


Co-authored-by: Mu-An Chiou <[email protected]>
Co-authored-by: James Craig <[email protected]>
Co-authored-by: James Nurthen <[email protected]>
Co-authored-by: pkra <[email protected]>

Author: 5 people

index.html

@@ -13082,13 +13082,34 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
         <div class="property" id="aria-controls">
           <pdef>aria-controls</pdef>
           <div class="property-description">
-            <p><a>Identifies</a> the <a>element</a> (or elements) whose contents or presence are controlled by the current element. See related <pref>aria-owns</pref>.</p>
-            <p>For example:</p>
+            <p>
+              <a>Identifies</a> the <a>element</a> (or elements) whose contents or presence are controlled by the focused element or composite widget. See related <pref>aria-details</pref> and
+              <pref>aria-owns</pref>.
+            </p>
+            <p>
+              The <code>aria-controls</code> property is for referencing elements that are modified by the user interacting with the currently focused element or composite widget. The presence of
+              <code>aria-controls</code> enables <a>assistive technologies</a> to programmatically associate the currently focused element with the element or elements it controls. For instance, it
+              can be used to inform users that by interacting with the controlling element they have revealed an element or elements that were previously in the hidden state. Or, by interacting with
+              an element, they caused the selection or value of a controlled element to change.
+            </p>
+            <p>Instance where an <code>aria-controls</code> association could be made:</p>
             <ul>
-              <li>A table of contents tree view can control the content of a neighboring document pane.</li>
-              <li>A group of checkboxes can control what commodity prices are tracked live in a table or graph.</li>
-              <li>A tab controls the display of its associated tab panel.</li>
+              <li>
+                Interacting with a text field or editable combobox results in the display of a listbox popup. Upon entering text, the associated listbox is filtered, or the selected option changes to
+                match the text value entered by the user.
+              </li>
+              <li>A tree view representing a table of contents where choosing a treeitem updates content of a neighboring document pane.</li>
+              <li>A series of checkboxes can each control what commodity prices are tracked live in a table or graph.</li>
+              <li>
+                An interactive element reveals associated content when selected. For instance, selecting a tab control reveals its associated tab panel. Or checking a radio button reveals additional
+                information or form controls related to the chosen radio button.
+              </li>
+              <li>Radio buttons allow for filtering to a listing of search results.</li>
             </ul>
+            <p>
+              Additionally, the <code>aria-controls</code> property supports multiple ID references. For example, a control can be used to highlight different instances of spelling errors. A user
+              agent MAY convey to a user that there are a number of related controlled elements (the misspellings), allow the user to navigate to the controlled elements in sequence, or both.
+            </p>
           </div>
           <table class="def">
             <caption>
@@ -13681,9 +13702,15 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
           <sdef>aria-expanded</sdef>
           <div class="state-description">
             <p><a>Indicates</a> whether a related element is expanded (shown) or collapsed (hidden).</p>
-            <p>The <sref>aria-expanded</sref> attribute is applied to a focusable, interactive element that toggles visibility of content of a different element. If the element with <sref>aria-expanded</sref> is also a <rref>treeitem</rref> in a <rref>tree</rref> or a <rref>row</rref> in a <rref>treegrid</rref>, then it SHOULD also be the <a>accessibility parent</a> of the content it expands and collapses. Otherwise, the element with <sref>aria-expanded</sref> SHOULD NOT be the <a>accessibility parent</a> of the content that is expanding or collapsing. Rather, identify that relationship between the interactive element and the element being controlled using <pref>aria-controls</pref>.</p>
+            <p>
+              The <sref>aria-expanded</sref> attribute is applied to a focusable, interactive element that toggles visibility of content of a different element. If the element with
+              <sref>aria-expanded</sref> is also a <rref>treeitem</rref> in a <rref>tree</rref> or a <rref>row</rref> in a <rref>treegrid</rref>, then it SHOULD also be the
+              <a>accessibility parent</a> of the content it expands and collapses. Otherwise, the element with <sref>aria-expanded</sref> SHOULD NOT be the <a>accessibility parent</a> of the content
+              that is expanding or collapsing. Rather, identify that relationship between the interactive element and the element being controlled using <pref>aria-controls</pref>.
+            </p>
             <p>For example, <sref>aria-expanded</sref> is applied to a parent <rref>treeitem</rref> to indicate whether its child branch of the tree is shown.</p>
-            <pre class="example highlight">&lt;ul role="tree"&gt;
+            <pre class="example highlight">
+&lt;ul role="tree"&gt;
   &lt;li role="treeitem" aria-expanded="false" aria-selected="false"&gt;
     &lt;span&gt;Fruits&lt;/span&gt;
     &lt;ul role="group" hidden&gt;
@@ -13692,12 +13719,15 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
       &lt;li role="treeitem" aria-selected="false"&gt;Yuzu&lt;/li&gt;
     &lt;/ul&gt;
   &lt;/li&gt;
-&lt;/ul&gt;</pre>
+&lt;/ul&gt;</pre
+            >
             <p>Similarly, it can be applied to a <rref>button</rref> to control the visibility of another element and its content on the current page.</p>
-            <pre class="example highlight">&lt;button type="button" aria-controls="mangosteen" aria-expanded="false"&gt;Mangosteen&lt;/button&gt;
+            <pre class="example highlight">
+&lt;button type="button" aria-controls="mangosteen" aria-expanded="false"&gt;Mangosteen&lt;/button&gt;
 &lt;div id="mangosteen" hidden&gt;
   An edible fruit native to tropical lands surrounding the Indian Ocean.
-&lt;/div&gt;</pre>
+&lt;/div&gt;</pre
+            >
           </div>
           <table class="def">
             <caption>