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.

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

Jump to bottom

Define concept of minimum role #454

Closed
wants to merge 30 commits into from
Closed

Define concept of minimum role #454

Changes from 8 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
3efda34
Update index.html
scottaohara Jan 10, 2023
b462c24
update per Aaron's review
scottaohara Jan 10, 2023
c6bae18
grammar fix
stevefaulkner Jan 16, 2023
cc5b7ab
Update index.html
scottaohara Jan 19, 2023
b1fdcde
Update index.html
scottaohara Jan 19, 2023
be28084
remove stray fragment
scottaohara Jan 24, 2023
c1a3f1f
minor markup formatting adjustment
scottaohara Jan 24, 2023
e2ac6f8
clarify minimum role conditions
scottaohara Jan 24, 2023
19a12bd
reverts typo fix
scottaohara Jan 31, 2023
ef36600
Merge branch 'gh-pages' into minimum-role
scottaohara Jan 31, 2023
02f6b5a
Update index.html
scottaohara Jan 31, 2023
f7ba989
Merge branch 'gh-pages' into minimum-role
scottaohara Feb 2, 2023
ed50c33
remove contenteditable from taking part in minimum role
scottaohara Mar 2, 2023
efb7337
Merge branch 'gh-pages' into minimum-role
scottaohara Apr 8, 2023
e7b17f7
Merge branch 'gh-pages' into minimum-role
scottaohara Apr 11, 2023
69513e2
edits to the steps to determine minimum role
scottaohara Apr 24, 2023
c013064
Update index.html
scottaohara May 10, 2023
6257a68
Merge branch 'gh-pages' into minimum-role
scottaohara May 10, 2023
fbe8161
Merge branch 'gh-pages' into minimum-role
scottaohara May 15, 2023
df7200a
Merge branch 'gh-pages' into minimum-role
scottaohara May 19, 2023
4519a4e
Merge branch 'gh-pages' into minimum-role
scottaohara Aug 17, 2023
6adfe58
edits to mention 'computed role'
scottaohara Aug 17, 2023
1e217e1
Merge branch 'gh-pages' into minimum-role
scottaohara Aug 18, 2023
8bd08ac
Merge branch 'gh-pages' into minimum-role
scottaohara Nov 7, 2023
e6b5963
Update index.html
scottaohara Nov 7, 2023
899b517
missing #
scottaohara Nov 7, 2023
8bcae45
Update index.html
scottaohara Nov 7, 2023
796734e
leave out tabindex for now
scottaohara Nov 7, 2023
ea628aa
Merge branch 'gh-pages' into minimum-role
scottaohara Dec 19, 2023
fb66dfd
Merge branch 'gh-pages' into minimum-role
scottaohara Mar 5, 2024
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
90 changes: 66 additions & 24 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,32 +215,64 @@ <h3>Exposing HTML Features That Do Not Directly Map to Accessibility APIs</h3>
</p>
</section>
<section>
<h3>HTML Element Role Mappings</h3>
<h3 id="minimum-role">Exposing HTML Features That Require a Minimum Role</h3>
<p>
A <dfn>minimum role</dfn> is the equivalent WAI-ARIA role an element will map to if the element has no more specific implicit role, e.g., a non-generic role. This can help ensure that users of assistive technologies get the best possible experience for commonly-used and valid HTML markup where otherwise a role would not be exposed.
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
</p>
<p>
A minimum role is provided when all of the following conditions are true:
</p>
<ul>
<li>HTML elements with implicit WAI-ARIA role semantics MUST be mapped to platform <a class="termref">accessibility APIs</a> according to the identified WAI-ARIA role mapping as defined in the [[core-aam-1.2]] specification.</li>
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
<li>"Not mapped" means the element does not need to be exposed via an <a class="termref">accessibility API</a>. This is usually because the element is not displayed as part of the user interface. However, authors can force some of these elements to be rendered. For instance, by overriding user agent styles to render elements that would have been otherwise set to `display: none`. In these cases, the user agent SHOULD map such elements to the role of <a class="core-mapping" href="#role-map-generic">`generic`</a>.</li>
<li>Where applicable, how an element participates in the computation of its own or another element's <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> and/or <a data-cite="accname-1.2/#dfn-accessible-description">accessible description</a> is described in the <a href="#accessible-name-and-description-computation">Accessible Name and Description Computation</a> section of this document.</li>
<li>Where an element is indicated as having &quot;No corresponding (WAI-ARIA) role&quot;, or is mapped to the <a class="core-mapping" href="#role-map-generic">`generic`</a> role, user agents MUST NOT expose the <a class="core-mapping" href="#ariaRoleDescription">`aria-roledescription`</a> property value in the <a class="termref">accessibility tree</a> unless the element has an explicit, conforming `role` attribute value which [[WAI-ARIA-1.2]] does not prohibit the use of `aria-roledescription`.</li>
<li>
<strong>IAccessible2:</strong>
<ul>
<li>All elements with accessible objects should implement the IAccessible, IAccessible2 and IAccessible2_2 interfaces.</li>
</ul>
the element either has no implicit mapping or has an implicit `generic` role mapping,
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
</li>
<li>
<strong>UIA:</strong>
<ul>
<li>When a <a data-cite="html/forms.html#category-label">labelable element</a> is referenced by a `label` element's `for` attribute, or a descendant of a `label` element, the labelable element's UIA `LabeledBy` property points to the UIA element for the `label` element.</li>
<li>Elements mapped to the `Text` Control Type are not generally represented as <a class="termref" data-lt="accessible object">accessible objects</a> in the <a class="termref">accessibility tree</a>, but are just part of the `Text` Control Pattern implemented for the whole HTML document. However, if they have any `aria-` attributes or an explicit `tabindex` specified, elements mapped to the `Text` Control Type will be represented as <a class="termref" data-lt="accessible object">accessible objects</a> in the <a class="termref">accessibility tree</a>.</li>
</ul>
the author has not specified an explicit role to the element,
<strong>or</strong> the author has specified an explicit role of `none`, `presentation`, or `generic` to the element,
</li>
<li>
<strong>AXAPI:</strong>
<ul>
<li>User agents should return a user-presentable, localized string value for the Mac Accessibility AXRoleDescription.</li>
</ul>
and the author has specified properties which require a minimum role mapping for the element.
</li>
</ul>
<p>
The properties which will require a minimum role mapping are specific global HTML attributes, identified in the <a href="#attribute-mapping-table">Mappings of HTML attributes table</a>.
</p>
<p>
When these conditions are met, the browser MUST expose an object using the mappings defined in CORE-AAM for the specified minimum role.
</p>
</section>
<section>
<h3>HTML Element Role Mappings</h3>
<ul>
<li>HTML elements with implicit WAI-ARIA role semantics MUST be mapped to platform <a class="termref">accessibility APIs</a> according to the identified WAI-ARIA role mapping as defined in the [[core-aam-1.2]] specification.</li>
<li>"Not mapped" means the element is not exposed via an <a class="termref">accessibility API</a>. Commonly, an element is not mapped because it's not displayed as part of the user interface. However, authors can force some of these elements to be rendered. For instance, by overriding user agent styles to render elements that would have been otherwise set to `display: none`. In these cases, the user agent SHOULD map such elements to the role of <a class="core-mapping" href="#role-map-generic">`generic`</a>, unless other HTML features have been specified which would require a more specific <a>minimum role</a> to be exposed.</li>
<li>Where an element is indicated as having <q>No corresponding (WAI-ARIA) role</q>, or is mapped to the <a class="core-mapping" href="#role-map-generic">`generic`</a> role, user agents MUST NOT expose the <a class="core-mapping" href="#ariaRoleDescription">`aria-roledescription`</a> property value in the <a class="termref">accessibility tree</a> unless the element has an explicit, conforming `role` attribute value for which [[WAI-ARIA-1.2]] does not prohibit the use of `aria-roledescription`.</li>
<li>Some HTML elements expose implicit WAI-ARIA roles depending on whether they have been provided an <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a>. How an element participates in the computation of its own or another element's <a data-cite="accname-1.2/#dfn-accessible-name">accessible name</a> and/or <a data-cite="accname-1.2/#dfn-accessible-description">accessible description</a> is described in the <a href="#accessible-name-and-description-computation">Accessible Name and Description Computation</a> section of this document.</li>
</ul>
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
<section>
<h4 id=foo>Platform API mapping requirements</h4>
<ul>
<li>
<strong>IAccessible2:</strong>
<ul>
<li>All elements with accessible objects SHOULD implement the IAccessible, IAccessible2 and IAccessible2_2 interfaces.</li>
</ul>
</li>
<li>
<strong>UIA:</strong>
<ul>
<li>When a <a data-cite="html/forms.html#category-label">labelable element</a> is referenced by a `label` element's `for` attribute, or a descendant of a `label` element, the labelable element's UIA `LabeledBy` property points to the UIA element for the `label` element.</li>
<li>Elements mapped to the `Text` Control Type are not generally represented as <a class="termref" data-lt="accessible object">accessible objects</a> in the <a class="termref">accessibility tree</a>, but are just part of the `Text` Control Pattern implemented for the whole HTML document. However, if they have any `aria-` attributes or an explicit `tabindex` specified, elements mapped to the `Text` Control Type will be represented as <a class="termref" data-lt="accessible object">accessible objects</a> in the <a class="termref">accessibility tree</a>.</li>
</ul>
</li>
<li>
<strong>AXAPI:</strong>
<ul>
<li>User agents should return a user-presentable, localized string value for the Mac Accessibility AXRoleDescription.</li>
</ul>
</li>
</ul>
</section>
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
<div class="table-container">
<table class="map-table elements" id="element-mapping-table">
<caption>Mappings of HTML elements to platform <a class="termref">accessibility APIs</a>: ARIA, MSAA + UIA Express, MSAA + IAccessible2, UIA, ATK, and AX</caption>
Expand Down Expand Up @@ -3318,7 +3350,9 @@ <h3>HTML Attribute State and Property Mappings</h3>
</div>
</td>
<td class="ax">`AXAccessKey: &lt;value&gt;`</td>
<td class="comments"></td>
<td class="comments">
Provides a <a href="termref">minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.
</td>
</tr>
<tr tabindex="-1" id="att-action">
<th>`action`</th>
Expand Down Expand Up @@ -3493,7 +3527,7 @@ <h3>HTML Attribute State and Property Mappings</h3>
<td class="atk"><div class="general">Not mapped</div></td>
<td class="ax"><div class="general">Not mapped</div></td>
<td class="comments">
<p>Similar to <a class="core-mapping" href="#ariaFlowto">`aria-flowto`</a>.</p>
Provides a <a href="termref">minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.
</td>
</tr>
<tr tabindex="-1" id="att-autoplay">
Expand Down Expand Up @@ -3674,11 +3708,15 @@ <h3>HTML Attribute State and Property Mappings</h3>
</td>
<td class="ax">
<span class="type">Role:</span>
<a href="#el-textarea">AXtextArea</a>
<a href="#el-textarea">AXTextArea</a>
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
<div class="general">Use WAI-ARIA mapping</div>
scottaohara marked this conversation as resolved.
Show resolved Hide resolved
</td>
<td class="comments">
If the element has the `contenteditable` attribute and `aria-readonly="true"`, User Agents MUST expose only the `contenteditable` state.
<p>If the element has the `contenteditable` attribute and `aria-readonly="true"`, User Agents MUST expose only the `contenteditable` state.</p>
<p>
If the attribute exposes or inherits the `true` state, it provides a <a href="termref">minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.
</p>
<!-- note: when/if contenteditable=plaintext-only becomes a standard, then this would have a minimum mapping of textbox -->
</td>
</tr>
<tr tabindex="-1" id="att-controls">
Expand Down Expand Up @@ -3917,7 +3955,9 @@ <h3>HTML Attribute State and Property Mappings</h3>
</div>
</td>
<td class="ax"><div class="general">Not mapped</div></td>
<td class="comments"></td>
<td class="comments">
Provides a <a href="termref">minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.
</td>
</tr>
<tr tabindex="-1" id="att-enctype">
<th>`enctype`</th>
Expand Down Expand Up @@ -5336,7 +5376,9 @@ <h3>HTML Attribute State and Property Mappings</h3>
<td class="uia"><div class="general">Use WAI-ARIA mapping</div></td>
<td class="atk"><div class="general">Use WAI-ARIA mapping</div></td>
<td class="ax"><div class="general">Use WAI-ARIA mapping</div></td>
<td class="comments"></td>
<td class="comments">
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that Hunseop Jeong has implemented this in https://chromium-review.googlesource.com/c/chromium/src/+/4794310 I have questions, because I realize we used to repair nameless occurances of <div tabindex=0> by computing name from contents. We will no longer be doing this, which could break things like:

<p>I don't know what I'm doing but <div tabindex="0" onclick="clicked()">Click me</div></p>

Should we care about that?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Firefox doesn't seem to add name from content to

which matches the ARIA spec regarding generic role. I think having the behavior match for Chrome and Firefox will be a positive.
For JAWS, this change will cause JAWS to announce "group" on focus, but I thihnk that is fine. In addition, if chrome no longer adds name from content to generic elements, the cases where focus moves inside these generic elements with names will be less chatty.

Copy link
Member Author

@scottaohara scottaohara Sep 5, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there are kinda two different cases that should be considered here.

a generic element with a tabindex so that it's focusable or in the tab order. those fit under what brett mentioned.

then there are the generic elements with a tabindex which also have a click/some-kind-of event attached. and those are more likely to be things where maybe the name should be calculated to make up for the likely faux buttons being made (not saying they 'should' be buttons. we don't know...)

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose even without any changes to this PR, the fake <div tabindex=0 onclick> button will be accessible because the user will be able to read the contents in the virtual buffer. It might not act as nice as a real button, but that's arguably good.

So my next question is whether

should get the minimum group role, or whether we should just leave those alone.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i'd still say group. any more than that would make a lot of assumptions that could make the content more difficult to read / could still be wrong in terms of the role. e.g., maybe it's supposed to be a link. maybe it's not really supposed to be either... so stay with group to keep a consistent baseline

Provides a <a href="termref">minimum role</a> of <a class="core-mapping" href="#role-map-group">`group`</a>.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I think we should only do this for tabindex=0. If we do it for tabindex=-1, it might create a lot of noise on web pages where tabindex=-1 is put on random elements for hard-to-explain reasons.

We ran into this when we used to repair missing names on <div tabindex=-1> by computing the name from contents. It caused too much noise.

</td>
</tr>
<tr tabindex="-1" id="att-target">
<th>`target`</th>
Expand Down