revise caption definition (#1703)

scottaohara · web-flow · commit 2d2d3413a65c · 2022-04-29T09:10:54.000+02:00
* revise caption definition This change in the definition is related to the changes in `figure` and `figcaption` in HTML AAM: w3c/html-aam#359 and introduces the idea that a `caption` may contain structured content - and in this PR - `aria-details` is referenced as a way authors should reference such content if within a `caption` Additionally, this PR extends the definition to allow `caption` to be used for purposes of naming/describing a `group` or `radiogroup`, which fills some gaps from the dropped `legend` role. If these updates are accepted, this would help pave the way to resolve #1696 as well. * add in missing id to first example * fix spacing issues * include additional example
diff --git a/index.html b/index.html
@@ -1790,15 +1790,25 @@ <h2>Definition of Roles</h2>
 		<div class="role" id="caption">
 			<rdef>caption</rdef>
 			<div class="role-description">
-				<p>Visible content that names, and may also describe, a <rref>figure</rref>, <rref>table</rref>, <rref>grid</rref>, or <rref>treegrid</rref>.</p>
+				<p>Visible content that names, or describes a <rref>group</rref>, <rref>figure</rref>, <rref>table</rref>, <rref>grid</rref>, <rref>radiogroup</rref>, or <rref>treegrid</rref>.</p>
 				<p>When using <code>caption</code> authors SHOULD ensure:</p>
 				<ul>
-					<li>The <code>caption</code> is a direct child of a <rref>figure</rref>, <rref>table</rref>, <rref>grid</rref>, or <rref>treegrid</rref>.</li>
-					<li>The <code>caption</code> is the first child of a <rref>table</rref>, <rref>grid</rref>, or <rref>treegrid</rref>.</li>
-					<li>The <code>caption</code> is the first or last child of a <rref>figure</rref>.</li>
+					<li>The <code>caption</code> is a direct child of a <rref>group</rref>, <rref>figure</rref>, <rref>grid</rref>, <rref>radiogroup</rref>, <rref>table</rref>, or <rref>treegrid</rref>.</li>
+					<li>The <code>caption</code> is the first non-<code>generic</code> child of a <rref>group</rref>, <rref>radiogroup</rref>, <rref>grid</rref>, <rref>table</rref>, or <rref>treegrid</rref>.</li>
+					<li>The <code>caption</code> is the first or last non-<code>generic</code> child of a <rref>figure</rref>.</li>
 				</ul>
-				<p>Authors SHOULD set <pref>aria-labelledby</pref> on the parent <code>figure</code>, <code>table</code>, <code>grid</code>, or <rref>treegrid</rref> to reference the element with role <code>caption</code>. However, if a <code>caption</code> contains content that serves as both a name and description for its parent, authors MAY instead set <pref>aria-labelledby</pref> to reference an element within the <code>caption</code> that contains a concise name, and set <pref>aria-describedby</pref> to reference an element within the <code>caption</code> that contains the descriptive content.</p>
-
+				<p>If the <code>caption</code> represents an accessible name for its containing element, authors SHOULD specify <pref>aria-labelledby</pref> on the parent element to reference the element with role <code>caption</code>.</p>
+				
+				<pre class="example highlight">
+					&lt;div role="radiogroup" aria-labelledby="cap"&gt;
+				    &lt;div role="caption" id="cap"&gt;
+				      Choose your favorite fruit
+				    &lt;/div&gt;
+				    &lt;!-- ... --&gt;
+				</pre>
+				
+				<p>If a <code>caption</code> contains content that serves as both a name and description for its parent, authors MAY instead specify <pref>aria-labelledby</pref> to reference an element within the <code>caption</code> that represents the "name" of the parent element, and specify <pref>aria-describedby</pref> to reference an element within the <code>caption</code> that represents the descriptive content.</p>
+				
 				<pre class="example highlight">
 					&lt;div role="table" aria-labelledby="name" aria-describedby="desc"&gt;
 				    &lt;div role="caption"&gt;
@@ -1810,6 +1820,38 @@ <h2>Definition of Roles</h2>
 				    &lt;/div&gt;
 				    &lt;!-- ... --&gt;
 				</pre>
+				
+				<p>If the <code>caption</code> represents a long-form description, or if the description contains semantic elements which are important in understanding the description, authors MAY instead specify <pref>aria-labelledby</pref> to reference an element within the <code>caption</code> that represents the "name" of the parent element, and specify <pref>aria-details</pref> to reference an element within the <code>caption</code> that contains the descriptive content.</p>
+
+				<pre class="example highlight">
+					&lt;div role="figure" aria-labelledby="name" aria-details="details"&gt;
+					  &lt;!-- figure content here, such as a complex data viz SVG -->
+				    &lt;div role="caption"&gt;
+				      &lt;div id="name"&gt;Sales information for 20XX&lt;/div&gt;
+				      &lt;div id="details"&gt;
+				        This barchart represents the total amount of sales over the course
+				        of five years. &lt;a href="...">Sales information for last year&lt;/a> can
+				        be reviewed, or you can overlay &lt;button aria-pressed="false">previous year&lt;/button>
+				        information in this graphic.
+				      &lt;/div&gt;
+				    &lt;/div&gt;
+				    &lt;!-- ... --&gt;
+				</pre>
+				
+				<p>There may be instances where a <code>caption</code> contains only a description, without a suitable text string to serve as the accessible name for the parent element. In such instances, <pref>aria-label</pref> or <pref>aria-labelledby</pref> MAY be used to provide an accessible name, and the <code>caption</code> MAY be treated solely as descriptive content.
+					
+				<pre class="example highlight">
+					&lt;div role="figure" aria-label="Sales information" aria-details="details"&gt;
+					  &lt;!-- figure content here, such as a complex data viz SVG -->
+				    &lt;div role="caption" id="details"&gt;
+				      This barchart represents the total amount of sales over the course
+				      of five years. &lt;a href="...">Sales information for last year&lt;/a> can
+				      be reviewed, or you can overlay &lt;button aria-pressed="false">previous year&lt;/button>
+				      information in this graphic.
+				    &lt;/div&gt;
+				    &lt;!-- ... --&gt;
+				</pre>
+				
 			</div>
 			<table class="role-features">
 				<caption>Characteristics:</caption>
@@ -1838,7 +1880,11 @@ <h2>Definition of Roles</h2>
 					</tr>
 					<tr>
 						<th class="role-related-head" scope="row">Related Concepts:</th>
-						<td class="role-related"><code>&lt;caption&gt;</code> in [[HTML]] <br/> <code>&lt;figcaption&gt;</code> in [[HTML]]</td>
+						<td class="role-related">
+							<code>&lt;caption&gt;</code> in [[HTML]] <br> 
+							<code>&lt;figcaption&gt;</code> in [[HTML]] <br>
+							<code>&lt;legend&gt;</code> in [[HTML]]
+						</td>
 					</tr>
 					<tr>
 						<th class="role-scope-head" scope="row">Required Context Role:</th>
