Editorial: Clarify aria-expanded guidance (#1980)

Co-authored-by: Scott O'Hara <[email protected]>

Author: adampage

index.html

@@ -13680,16 +13680,24 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
         <div class="state" id="aria-expanded">
           <sdef>aria-expanded</sdef>
           <div class="state-description">
-            <p><a>Indicates</a> whether a grouping element that is the <a>accessibility child</a> of or is controlled by this element is expanded or collapsed.</p>
-            <p>
-              The <sref>aria-expanded</sref> attribute is applied to a focusable, interactive element that toggles visibility of content in another element. For example, it is applied to a parent
-              <rref>treeitem</rref> to indicate whether its child branch of the tree is shown. Similarly, it can be applied to a <rref>button</rref> that controls visibility of a section of page
-              content.
-            </p>
-            <p>
-              If a grouping container that can be expanded or collapsed is not the <a>accessibility child</a> of the element that has the <sref>aria-expanded</sref> attribute, the author SHOULD
-              identify the controlling relationship by referencing the container from the element that has <sref>aria-expanded</sref> with the <pref>aria-controls</pref> property.
-            </p>
+            <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>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;
+&lt;li role="treeitem" aria-expanded="false" aria-selected="false"&gt;
+  &lt;span&gt;Fruits&lt;/span&gt;
+  &lt;ul role="group" hidden&gt;
+    &lt;li role="treeitem" aria-selected="false"&gt;Apricot&lt;/li&gt;
+    &lt;li role="treeitem" aria-selected="false"&gt;Mangosteen&lt;/li&gt;
+    &lt;li role="treeitem" aria-selected="false"&gt;Yuzu&lt;/li&gt;
+  &lt;/ul&gt;
+&lt;/li&gt;
+&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;
+&lt;div id="mangosteen" hidden&gt;
+  An edible fruit native to tropical lands surrounding the Indian Ocean.
+&lt;/div&gt;</pre>
           </div>
           <table class="def">
             <caption>