Skip to content

Commit

Permalink
revise caption definition (#1703)
Browse files Browse the repository at this point in the history 
* 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
  • Loading branch information
@scottaohara @jnurthen
scottaohara authored and jnurthen committed Oct 10, 2023
1 parent c2adaeb commit 82ae4b4
Showing 1 changed file with 53 additions and 7 deletions.
60 changes: 53 additions & 7 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1800,15 +1800,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;
Expand All @@ -1820,6 +1830,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>
Expand Down Expand Up @@ -1848,7 +1890,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>
Expand Down

0 comments on commit 82ae4b4

Please sign in to comment.