Skip to content

Editorial: Clarify / make consistent naming steps for HTML form controls #2395

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.

Sign up for GitHub

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

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
+67 −31
Open

Editorial: Clarify / make consistent naming steps for HTML form controls #2395

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
03ddaad
Update index.html
scottaohara Dec 9, 2024
28aabbe
Update html-aam/index.html
scottaohara Jan 10, 2025
0574649
Merge branch 'main' into form-control-naming-updates
scottaohara Jan 28, 2025
e7a2567
Merge branch 'main' into form-control-naming-updates
scottaohara May 10, 2025
0e47005
chore: prettier
scottaohara May 10, 2025
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
79 changes: 53 additions & 26 deletions html-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16343,7 +16343,7 @@ <h2>Accessible Name and Description Computation</h2>
<h3>Accessible Name Computations By HTML Element</h3>
<section>
<h4>
`input type="text"`, `input type="password"`, `input type="number"`, `input type="search"`,` input type="tel"`, `input type="email"`, `input type="url"` and `textarea` Element Accessible
`input type="text"`, `input type="password"`, `input type="number"`, `input type="search"`,` input type="tel"`, `input type="email"`, `input type="url"` and `textarea` Elements Accessible
Name Computation
</h4>
<ol>
Expand All @@ -16353,55 +16353,75 @@ <h4>
<a href="" class="accname">Accessible Name and Description: Computation and API Mappings</a>.
</li>
<li>
Otherwise use the associated `label` element or elements <a data-cite="accname-1.2/#dfn-accessible-name">accessible name(s)</a> - if more than one `label` is associated; concatenate by
DOM order, delimited by spaces.
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the <a data-cite="accname-1.2/#mapping_additional_nd_te">text equivalent computation</a> of
the associated `label` element's subtree - if more than one `label` is associated; concatenate their subtrees by DOM order, delimited by spaces.
<p>
If the control is encapsulated by its `label` element, exclude the control's author specified or user-entered value from its computed
<a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.
</p>
</li>
<li>If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty, then: use the control's `title` attribute.</li>
<li>Otherwise use the control's <a href="#att-placeholder">placeholder</a> value.</li>
<li>If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the value of the control's `title` attribute.</li>
<li>Otherwise: use the value of the control's <a href="#att-placeholder">placeholder</a> attribute.</li>
<li>If none of the above yield a usable text string there is no <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.</li>
</ol>
</section>
<section>
<h4>`input type="button"`, `input type="submit"` and `input type="reset"` Accessible Name Computation</h4>
<h4>`input type="button"`, `input type="submit"` and `input type="reset"` Elements Accessible Name Computation</h4>
<ol>
<li>
If the control has an <a data-cite="wai-aria-1.2/#aria-label">`aria-label`</a> or an <a data-cite="wai-aria-1.2/#aria-labelledby">`aria-labelledby`</a> attribute the
<a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is to be calculated using the algorithm defined in
<a href="" class="accname">Accessible Name and Description: Computation and API Mappings</a>.
</li>
<li>
Otherwise use the associated `label` element(s) <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>(s) - if more than one `label` is associated; concatenate by DOM order,
delimited by spaces.
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the <a data-cite="accname-1.2/#mapping_additional_nd_te">text equivalent computation</a> of
the associated `label` element's subtree - if more than one `label` is associated; concatenate their subtrees by DOM order, delimited by spaces.
<p>
If the control is encapsulated by its `label` element, and the control has an author specified `value` or the lack of a `value` has produced an
<a href="https://infra.spec.whatwg.org/#implementation-defined">implementation defined</a> string to render, then exclude either from the control's computed
<a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.
</p>
</li>
<li>Otherwise use the `value` attribute.</li>
<li>If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the value of the control's `value` attribute.</li>
<li>
For `input type=submit` and `type=reset`: if the prior steps do not yield a usable text string, and the `value` attribute is unspecified use the
<a href="https://infra.spec.whatwg.org/#implementation-defined">implementation defined</a> string respective to the input type.
For `input type=submit` and `type=reset`: if the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty, and the `value` attribute is unspecified, use the
<a href="https://infra.spec.whatwg.org/#implementation-defined">implementation defined</a> string respective to the input type. For instance, a localized string of the word "submit" or
"reset" respective to the type of `input`.
</li>
<li>Otherwise, if the control still has no <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> use `title` attribute.</li>
<li>Otherwise: use the value of the control's `title` attribute.</li>
<li>If none of the above yield a usable text string there is no <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.</li>
</ol>
</section>
<section>
<h4>`input type="image"` Accessible Name Computation</h4>
<h4>`input type="image"` Element Accessible Name Computation</h4>
<ol>
<li>
If the control has an <a data-cite="wai-aria-1.2/#aria-label">`aria-label`</a> or an <a data-cite="wai-aria-1.2/#aria-labelledby">`aria-labelledby`</a> attribute the
<a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is to be calculated using the algorithm defined in
<a href="" class="accname">Accessible Name and Description: Computation and API Mappings</a>.
</li>
<li>
Otherwise use the associated `label` element(s) <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>(s) - if more than one `label` is associated; concatenate by DOM order,
delimited by spaces.
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the <a data-cite="accname-1.2/#mapping_additional_nd_te">text equivalent computation</a> of
the associated `label` element's subtree - if more than one `label` is associated; concatenate their subtrees by DOM order, delimited by spaces.
<p>
If the control is encapsulated by its `label` element, and the control has an `alt` attribute, then exclude the attribute's value from the control's computed
<a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.
</p>
</li>
<li>
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the value of the control's `alt` attribute if present and its value is not the empty
string.
</li>
<li>Otherwise use `alt` attribute if present and its value is not the empty string.</li>
<!-- NOTE: use of value attribute is invalid on input type=image, but it DOES contribute to the name if used -->
<!-- <li>Otherwise use `value` attribute.</li> -->
<li>Otherwise use `title` attribute if present and its value is not the empty string.</li>
<!-- NOTE: use of value attribute is invalid on input type=image, but it DOES contribute to the name if used.
if this were to be specified, it'd belong here in the steps -->
<li>
Otherwise if the previous steps do not yield a usable text string, use the
<a href="https://infra.spec.whatwg.org/#implementation-defined">implementation defined</a> string respective to the input type (an `input` in the `image` state represents a
<a data-cite="html/forms.html#concept-submit-button">submit button</a>). For instance, a localized string of the word "submit" or the words &quot;Submit Query&quot;.
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the value of the control's `title` attribute if present and its value is not the empty
string.
</li>
<li>
Otherwise, if the previous steps do not yield a usable text string: use the <a href="https://infra.spec.whatwg.org/#implementation-defined">implementation defined</a> string respective
to the input type (an `input` in the `image` state represents a <a data-cite="html/forms.html#concept-submit-button">submit button</a>). For instance, a localized string of the word
"submit" or the words &quot;Submit Query&quot;.
</li>
<li>If none of the above yield a usable text string there is no <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.</li>
</ol>
Expand All @@ -16415,11 +16435,18 @@ <h4>`button` Element Accessible Name Computation</h4>
<a href="" class="accname">Accessible Name and Description: Computation and API Mappings</a>.
</li>
<li>
Otherwise use the associated `label` element(s) <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>(s) - if more than one `label` is associated; concatenate by DOM order,
delimited by spaces.
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the <a data-cite="accname-1.2/#mapping_additional_nd_te">text equivalent computation</a> of
the associated `label` element's subtree - if more than one `label` is associated; concatenate their subtrees by DOM order, delimited by spaces.
<p>
If the `button` element is encapsulated by its `label` element, ignore the `button` element's subtree from its computed
<a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.
</p>
</li>
<li>
If the <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> is still empty: use the <a data-cite="accname-1.2/#mapping_additional_nd_te">text equivalent computation</a> of
the element's subtree.
</li>
<li>Otherwise use the `button` element subtree.</li>
<li>Otherwise use `title` attribute.</li>
<li>Otherwise: use the value of the element's `title` attribute.</li>
<li>If none of the above yield a usable text string there is no <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>.</li>
</ol>
</section>
Expand Down
19 changes: 14 additions & 5 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13681,9 +13681,15 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<sdef>aria-expanded</sdef>
<div class="state-description">
<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>
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;
<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;
Expand All @@ -13692,12 +13698,15 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
&lt;li role="treeitem" aria-selected="false"&gt;Yuzu&lt;/li&gt;
&lt;/ul&gt;
&lt;/li&gt;
&lt;/ul&gt;</pre>
&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;
<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>
&lt;/div&gt;</pre
>
</div>
<table class="def">
<caption>
Expand Down