Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft: Add secondary action buttons as allowed child roles #1498

Closed
wants to merge 3 commits into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions common/terms.html
Original file line number Diff line number Diff line change
Expand Up @@ -53,10 +53,22 @@
<dd>
<p>In this specification, attribute is used as it is in markup languages. Attributes are structural features added to <a class="termref" href="#dfn-element">elements</a> to provide information about the <a class="termref" href="#dfn-state">states</a> and <a class="termref" href="#dfn-property">properties</a> of the <a class="termref" href="#dfn-object">object</a> represented by the element.</p>
</dd>
<dt><dfn data-lt="owned child|child element|child|children|child elements">Owned Child</dfn></dt>
<dd>
<p>An 'owned child' is a direct <abbr title="Document Object Model">DOM</abbr> child of the <a>element</a>, a descendant of the <a>element</a> with only <rref>generic</rref> or <rref>presentation</rref> elements intervening, or a child specified via an <pref>aria-owns</pref> relationship to the element.</p>
</dd>
<dt><dfn data-lt="class|classes">Class</dfn></dt>
<dd>
<p>A set of instance <a class="termref" href="#dfn-object">objects</a> that share similar characteristics.</p>
</dd>
<dt><dfn data-lt="controlled element|controlled|controlled element's|controlled elements">Controlled Element</dfn></dt>
<dd>
<p>A 'controlled element' is any <a class="termref" href="#dfn-element">element</a> referenced by <code>id</code> via <pref>aria-controls</pref>.</p>
</dd>
<dt><dfn data-lt="controlling element|controlling">Controlling Element</dfn></dt>
<dd>
<p>A 'controlling element' is any <a class="termref" href="#dfn-element">element</a> with an <pref>aria-controls</pref> attribute which references the ID of the element. </p>
</dd>
<dt><dfn data-lt="deprecated|deprecate|deprecation">Deprecated</dfn></dt>
<dd>
<p>A deprecated <a class="termref" href="#dfn-role">role</a>, <a class="termref" href="#dfn-state">state</a>, or <a class="termref" href="#dfn-property">property</a> is one which has been outdated by newer constructs or changed circumstances, and which may be removed in future versions of the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> specification. <a class="termref" data-lt="user agent">User agents</a> are encouraged to continue to support items identified as deprecated for backward compatibility. For more information, see <a href="#deprecated" class="specref">Deprecated Requirements</a> in the Conformance section.</p>
Expand Down Expand Up @@ -144,6 +156,10 @@
<dd>
<p>An 'owning element' is any <abbr title="Document Object Model">DOM</abbr> ancestor of the <a>element</a>, or any element with an <pref>aria-owns</pref> attribute which references the ID of the element. </p>
</dd>
<dt><dfn data-lt="parent element|parent">Parent Element</dfn></dt>
<dd>
<p>A 'parent element' is a direct <abbr title="Document Object Model">DOM</abbr> parent of the <a>element</a>, an ancestor of the <a>element</a> with only <rref>generic</rref> or <rref>presentation</rref> elements intervening, or any element with a child specified via <pref>aria-owns</pref>.</p>
</dd>
<dt><dfn>Perceivable</dfn></dt>
<dd>
<p>Presentable to users in ways they can sense. References in this document relate to <cite><a href="https://www.w3.org/TR/WCAG21/#perceivable"><abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1 Principle 1: Content must be perceivable</a></cite> [[WCAG21]].</p>
Expand Down
49 changes: 31 additions & 18 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -294,6 +294,14 @@ <h1>Important Terms</h1>
<dd>
<p>A set of instance <a class="termref" href="#dfn-object">objects</a> that share similar characteristics.</p>
</dd>
<dt><dfn data-lt="controlled element|controlled|controlled element's|controlled elements">Controlled Element</dfn></dt>
<dd>
<p>A 'controlled element' is any <a class="termref" href="#dfn-element">element</a> referenced by <code>id</code> via <pref>aria-controls</pref>.</p>
</dd>
<dt><dfn data-lt="controlling element|controlling">Controlling Element</dfn></dt>
<dd>
<p>A 'controlling element' is any <a class="termref" href="#dfn-element">element</a> with an <pref>aria-controls</pref> attribute which references the ID of the element. </p>
</dd>
<dt><dfn data-export="" data-lt="deprecated|deprecate|deprecation">Deprecated</dfn></dt>
<dd>
<p>A deprecated <a class="termref" href="#dfn-role">role</a>, <a class="termref" href="#dfn-state">state</a>, or <a class="termref" href="#dfn-property">property</a> is one which has been outdated by newer constructs or changed circumstances, and which may be removed in future versions of the <abbr title="Accessible Rich Internet Applications">WAI-ARIA</abbr> specification. <a class="termref" data-lt="user agent">User agents</a> are encouraged to continue to support items identified as deprecated for backward compatibility. For more information, see <a href="#deprecated" class="specref">Deprecated Requirements</a> in the Conformance section.</p>
Expand Down Expand Up @@ -388,14 +396,18 @@ <h1>Important Terms</h1>
<dd>
<p>Usable by users in ways they can control. References in this document relate to <cite><a href="https://www.w3.org/TR/WCAG21/#operable"><abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1 Principle 2: Content must be operable</a></cite> [[WCAG21]]. See <a>Keyboard Accessible</a>.</p>
</dd>
<dt><dfn data-export="" data-lt="owned element|owned|owned element's|owned elements">Owned Element</dfn></dt>
<dt><dfn data-export="" data-lt="owned child|child element|child|children|child elements">Owned Child</dfn></dt>
<dd>
<p>An 'owned element' is any <abbr title="Document Object Model">DOM</abbr> descendant of the <a>element</a>, any element specified as a child via <pref>aria-owns</pref>, or any <abbr title="Document Object Model">DOM</abbr> descendant of the owned child.</p>
<p>An 'owned child' is a direct <abbr title="Document Object Model">DOM</abbr> child of the <a>element</a>, a descendant of the <a>element</a> with only <rref>generic</rref> or <rref>presentation</rref> elements intervening, or a child specified via an <pref>aria-owns</pref> relationship to the element.</p>
</dd>
<dt><dfn data-export="" data-lt="owning element|owning">Owning Element</dfn></dt><!--Not used-->
<dd>
<p>An 'owning element' is any <abbr title="Document Object Model">DOM</abbr> ancestor of the <a>element</a>, or any element with an <pref>aria-owns</pref> attribute which references the ID of the element. </p>
</dd>
<dt><dfn data-export="" data-lt="parent element|parent">Parent Element</dfn></dt>
<dd>
<p>An 'parent element' is a direct <abbr title="Document Object Model">DOM</abbr> parent of the <a>element</a>, an ancestor of the <a>element</a> with only <rref>generic</rref> or <rref>presentation</rref> elements intervening, or any element with a child specified via <pref>aria-owns</pref>.</p>
</dd>
<dt><dfn data-export="">Perceivable</dfn></dt>
<dd>
<p>Presentable to users in ways they can sense. References in this document relate to <cite><a href="https://www.w3.org/TR/WCAG21/#perceivable"><abbr title="Web Content Accessibility Guidelines">WCAG</abbr> 2.1 Principle 1: Content must be perceivable</a></cite> [[WCAG21]].</p>
Expand Down Expand Up @@ -663,18 +675,18 @@ <h3>Prohibited States and Properties</h3>
<p class="note">A host language attribute with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> would also prohibit a state or property in this section. </p>
</section>
<section id="mustContain">
<h3>Required Owned Elements</h3>
<p>Any <a>element</a> that will be <a>owned</a> by the element with this <a>role</a>. For example, an element with the role <rref>list</rref> will own at least one element with the role <rref>listitem</rref>.</p>
<p>When multiple roles are specified as <em>required owned elements</em> for a role, at least one instance of one required <a>owned</a> element is expected. This specification does <em>not</em> require an instance of each of the listed owned roles. For example, a <code>menu</code> should have at least one instance of a <code>menuitem</code>, <code>menuitemcheckbox</code>, <em>or</em> <code>menuitemradio</code>. The <code>menu</code> role does not require one instance of each. </p>
<p>There may be times that required <a>owned</a> elements are missing, for example, while editing or while loading a data set. When a widget is missing <em>required owned elements</em> due to script execution or loading, authors MUST mark a containing element with <sref>aria-busy</sref> equal to <code>true</code>. For example, until a page is fully initialized and complete, an author could mark the document element as busy.</p>
<p class="note">A role that has 'required owned elements' does not imply the reverse relationship. While processing of a role may be incomplete without elements of given roles present as descendants, elements with roles in this list do not always have to be found within elements of the given role. See <a href="#scope">required context role</a> for requirements about the context where elements of a given role will be contained.</p>
<p class="note">An element with a <a href="#subclassroles">subclass role</a> of the 'required owned element' does not fulfill this requirement. For example, the <rref>listbox</rref> role requires ownership of an element using the <rref>option</rref> or <rref>group</rref> role. Although the <rref>group</rref> role is the superclass of <rref>row</rref>, adding an <a>owned</a> element with a role of <rref>row</rref> will not fulfill the requirement that <rref>listbox</rref> owns an <rref>option</rref> or a <rref>group</rref>.</p>
<h3>Allowed Child Roles</h3>
<p>Any <a>element</a> that is a direct <a>child</a> of the element with this <a>role</a>. For example, an element with the role <rref>list</rref> may own elements with the role <rref>listitem</rref>, but not elements with the role <rref>option</rref>.</p>
<p>To determine whether an element is the direct <a>child</a> of a role, <a>user agents</a> MUST ignore any elements with the role <rref>generic</rref> or <rref>presentation</rref>.</p>
<p>Descendents which are not direct children of an element ancestor are not constrained by <em>allowed child roles</em>. For example, an <code>image</code> is not an allowed child of a <code>list</code>, but it is a valid descendent so long as it is also a descendant of the <code>list</code>'s allowed child <code>listitem</code>.</p>
<p class="note">A role that has 'allowed child roles' does not imply the reverse relationship. Elements with roles in this list do not always have to be found within elements of the given role. See <a href="#scope">allowed parent roles</a> for requirements about the context where elements of a given role will be contained.</p>
<p class="note">An element with a <a href="#subclassroles">subclass role</a> of the 'allowed child role' does not fulfill this requirement. For example, the <rref>listbox</rref> role allows a child element using the <rref>option</rref> or <rref>group</rref> role. Although the <rref>group</rref> role is the superclass of <rref>row</rref>, adding a child element with a role of <rref>row</rref> will not fulfill the requirement that <rref>listbox</rref> allows children with <rref>option</rref> or <rref>group</rref> roles.</p>
<p class="note">An element with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> fulfills this requirement.</p>
</section>
<section id="scope">
<h3>Required Context Role</h3>
<p>The required context role defines the owning container where this <a>role</a> is allowed. If a role has a required context, authors MUST ensure that an element with the role is contained inside (or <a>owned</a> by) an element with the required context role. For example, an element with role <code>listitem</code> is only meaningful when contained inside (or <a>owned</a> by) an element with role <code>list</code>.</p>
<p class="note">A role that has 'required context role' does not imply the reverse relationship. While an element with the given role needs to appear within an element of the listed role(s) in order to be meaningful, elements of the listed roles do not always need descendant elements of the given role in order to be meaningful. See <a href="#mustContain">required owned elements</a> for requirements about elements that require presence of a given descendant to be processed properly.</p>
<h3>Required Parent Role</h3>
<p>The required <a>parent</a> role defines the parent container where this <a>role</a> is allowed. If a role has a required parent, authors MUST ensure that an element with the role is a direct <a>child</a> of an element with the required parent role. For example, an element with role <code>listitem</code> is only meaningful when it is a child of an element with role <code>list</code>.</p>
<p>To determine whether an element has a parent with the required role, <a>user agents</a> MUST ignore any elements with the role <rref>generic</rref> or <rref>presentation</rref>.</p>
<p class="note">An element with the appropriate <a href="#implicit_semantics">implicit WAI-ARIA semantic</a> fulfills this requirement.</p>
</section>
<section id="namecalculation">
Expand Down Expand Up @@ -4853,15 +4865,16 @@ <h5>Note regarding the ARIA 1.3 <code>image</code> role.</h5>
</td>
</tr>
<tr>
<th class="role-scope-head" scope="row">Required Context Role:</th>
<th class="role-scope-head" scope="row">Required Parent Role:</th>
<td class="role-scope"> </td>
</tr>
<tr>
<th class="role-mustcontain-head" scope="row">Required Owned Elements:</th>
<th class="role-mustcontain-head" scope="row">Allowed Child Roles:</th>
<td class="role-mustcontain">
<ul>
<li><rref>group</rref> containing <rref>option</rref></li>
<li><rref>group</rref> with child <rref>option</rref></li>
<li><rref>option</rref></li>
<li><rref>button</rref> if <a>controlling</a> a child <rref>option</rref></li>
</ul>
</td>
</tr>
Expand Down Expand Up @@ -6295,16 +6308,16 @@ <h5>Note regarding the ARIA 1.1 <code>none</code> role.</h5>
</td>
</tr>
<tr>
<th class="role-scope-head" scope="row">Required Context Role:</th>
<th class="role-scope-head" scope="row">Required Parent Role:</th>
<td class="role-scope">
<ul>
<li><rref>listbox</rref></li>
<li><rref>group</rref> contained by <rref>listbox</rref></li>
<li><rref>group</rref> with parent <rref>listbox</rref></li>
</ul>
</td>
</tr>
<tr>
<th class="role-mustcontain-head" scope="row">Required Owned Elements:</th>
<th class="role-mustcontain-head" scope="row">Allowed Child Roles:</th>
<td class="role-mustcontain"> </td>
</tr>
<tr>
Expand Down Expand Up @@ -13833,7 +13846,7 @@ <h3>Presentational Roles Conflict Resolution</h3>
<p>User agents MUST NOT expose <a>elements</a> having explicit or inherited presentational role in the accessibility tree, with these exceptions:</p>
<ul>
<li>If an element is focusable, or otherwise interactive, user agents MUST ignore the <code>presentation</code> role and expose the element with its implicit role, in order to ensure that the element is <a>operable</a>.</li>
<li>If a <a href="#mustContain">required owned element</a> has an explicit non-presentational role, user agents MUST ignore an inherited presentational role and expose the element with its explicit role. If the action of exposing the explicit role causes the accessibility tree to be malformed, the expected results are undefined.</li>
<li>If an <a href="#mustContain">allowed child element</a> has an explicit non-presentational role, user agents MUST ignore an inherited presentational role and expose the element with its explicit role. If the action of exposing the explicit role causes the accessibility tree to be malformed, the expected results are undefined.</li>
<li>If an element has global WAI-ARIA states or properties, user agents MUST ignore the <code>presentation</code> role and expose the element with its implicit role. However, if an element has only non-global, role-specific WAI-ARIA states or properties, the element MUST NOT be exposed unless the presentational role is inherited and an explicit non-presentational role is applied.</li>
</ul>
<p>For example, <pref>aria-describedby</pref> is a global attribute and would always be applied; <pref>aria-level</pref> is not a global attribute and would therefore only apply if the element was not in a presentational state.</p>
Expand Down