Add comment role (#1135)

aleventhal · carmacleod · mcking65 · web-flow · commit eed0ef0eeb70 · 2020-02-11T09:27:34.000-08:00
Refers to issue #749 Co-Authored-By: Carolyn MacLeod <Carolyn_MacLeod@ca.ibm.com> Co-Authored-By: Matt King <a11yThinker@Gmail.com>
diff --git a/index.html b/index.html
@@ -640,6 +640,7 @@ <h3>Document Structure Roles</h3>
 				<li><rref>caption</rref></li>
 				<li><rref>cell</rref></li>
 				<li><rref>columnheader</rref></li>
+				<li><rref>comment</rref></li>
 				<li><rref>definition</rref></li>
 				<li><rref>deletion</rref></li>
 				<li><rref>directory</rref></li>
@@ -2327,6 +2328,107 @@ <h2>Definition of Roles</h2>
 				</tbody>
 			</table>
 		</div>
+		<div class="role" id="comment">
+			<rdef>comment</rdef>
+			<div class="role-description">
+				<p>A comment contains content expressing reaction to other content.</p>
+				<p>Comments can annotate any visible content, from small spans of text, to other comments, to entire articles. Authors SHOULD identify the relationships between comments and the commented content, as follows:</p>
+				<ol>
+					<li>If the comment is a reply to another <code>comment</code>:
+						<ul>
+							<li>If all ancestor comments are available in the DOM, make each reply <code>comment</code> a semantic descendant of the <code>comment</code> to which it is replying, either by making it a DOM descendant element or by using <pref>aria-owns</pref>.</li>
+							<li>Alternatively, if all ancestor comments are not in the DOM, such as when comments are paginated, the hierarchical
+								level MAY be indicated via <pref>aria-level</pref>. Additional group positional information MAY be indicated via <pref>aria-posinset</pref> and <pref>aria-setsize</pref>.</li>
+						</ul>
+					</li>
+					<li>Otherwise, if the comment relates to other content in the page:
+						<ul>
+							<li>Provide <pref>aria-details</pref> on the element containing the commented content with a value refering to the element with role <code>comment</code>.</li>
+							<li>If there are multiple comments related to the same commented content, either provide a value for <pref>aria-details</pref> on the commented content that refers to each individual comment, or use <pref>aria-details</pref> to refer to a parent container of the comments. If <pref>aria-details</pref> refers to an element containing comments rather than <code>comment</code> elements, authors SHOULD assign a role of <rref>group</rref> or <rref>region</rref> to the referenced container.</li>
+						</ul>
+					</li>
+				</ol>
+				<p>If the author has not explicitly declared <pref>aria-level</pref>, <pref>aria-posinset</pref>, or <pref>aria-setsize</pref> for a <code>comment</code> element, user agents MUST automatically compute the missing values and expose them to assistive technologies.</p>
+			</div>
+			<table class="role-features">
+				<caption>Characteristics:</caption>
+				<thead>
+					<tr>
+						<th scope="col">Characteristic</th>
+						<th scope="col">Value</th>
+					</tr>
+				</thead>
+				<tbody>
+					<tr>
+						<th class="role-abstract-head" scope="row">Is Abstract:</th>
+						<td class="role-abstract"> </td>
+					</tr>
+					<tr>
+						<th class="role-parent-head" scope="row">Superclass Role:</th>
+						<td class="role-parent"><rref>article</rref></td>
+					</tr>
+					<tr>
+						<th class="role-base-head" scope="row">Base Concept:</th>
+						<td class="role-base"> </td>
+					</tr>
+					<tr>
+						<th class="role-related-head" scope="row">Related Concepts:</th>
+						<td class="role-related"> </td>
+					</tr>
+					<tr>
+						<th class="role-scope-head" scope="row">Required Context Role:</th>
+						<td class="role-scope"> </td>
+					</tr>
+					<tr>
+						<th class="role-mustcontain-head" scope="row">Required Owned Elements:</th>
+						<td class="role-mustcontain"> </td>
+					</tr>
+					<tr>
+						<th class="role-required-properties-head">Required States and Properties:</th>
+						<td class="role-required-properties"> </td>
+					</tr>
+					<tr>
+						<th class="role-properties-head" scope="row">Supported States and Properties:</th>
+						<td class="role-properties">
+							<ul>
+								<li><pref>aria-level</pref></li>
+								<li><pref>aria-posinset</pref></li>
+								<li><pref>aria-setsize</pref></li>
+							</ul>
+						</td>
+					</tr>
+					<tr>
+						<th class="role-inherited-head" scope="row">Inherited States and Properties:</th>
+						<td class="role-inherited">Placeholder</td>
+					</tr>
+					<tr>
+						<th class="role-namefrom-head" scope="row">Name From:</th>
+						<td class="role-namefrom">
+							<ul>
+								<li>contents</li>
+								<li>author</li>
+							</ul>
+						</td>
+					</tr>
+					<tr>
+						<th class="role-namerequired-head" scope="row">Accessible Name Required:</th>
+						<td class="role-namerequired"> </td>
+					</tr>
+					<tr>
+						<th class="role-namerequired-inherited-head" scope="row">Inherits Name Required:</th>
+						<td class="role-namerequired-inherited"> </td>
+					</tr>
+					<tr>
+						<th class="role-childpresentational-head" scope="row">Children Presentational:</th>
+						<td class="role-childpresentational"> </td>
+					</tr>
+					<tr>
+						<th class="role-presentational-inherited-head" scope="row">Inherits Presentational:</th>
+						<td class="role-presentational-inherited"> </td>
+					</tr>
+				</tbody>
+			</table>
+		</div>
 		<div class="role" id="complementary">
 			<rdef>complementary</rdef>
 			<div class="role-description">
