Skip to content

Implement mappings for popover hint #2717

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
keithamus wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Implement mappings for popover hint #2717

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
c969abc
Implement mappings for popover=hint
keithamus Jan 19, 2026
0ef8771
Merge branch 'main' into implement-mappings-for-popover-hint
daniel-montalvo Jan 21, 2026
0ea67aa
add note around empty string
keithamus Feb 12, 2026
9d71eed
Merge branch 'main' into implement-mappings-for-popover-hint
keithamus Feb 12, 2026
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
76 changes: 63 additions & 13 deletions html-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -237,6 +237,26 @@ <h3 id="minimum-role">Exposing HTML Features That Require a Minimum Role</h3>
require a minimum role be returned as the computed role for the element, prioritize the more specific role in the ARIA taxonomy.
</p>
</section>
<section>
<h3 id="plain-content">Plain Content</h3>

@cookiecrook cookiecrook Jan 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Is there an HTML spec concept here we can reference instead? This overlaps the similar concept of block/flow content in a way that leaves ambiguity in my understanding of your intention.

@cookiecrook cookiecrook Jan 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

For example, images aren't always plain, as in the context of an animated SVG. Nor can an image (not even a bitmap) be referenced as plaintext, unless you bring in another concept like an object replacement character. This seems to blur the line, esp re: attributed strings and other similar rich text concepts like Flow contents.

@keithamus keithamus Jan 22, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

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

No this is somewhat of an ARIA semantic. At least in Chrome and how I've also implemented this in Firefox is to iterate over the popover & it's descendants and determine if the role matches.

I don't know if the heuristic is worth changing or the spec doesn't properly express this idea, but I am open to suggestions.

<p>
An element contains <dfn id="dfn-plain-content">plain content</dfn> when the element and all of its
<a class="termref" data-cite="wai-aria-1.2#dfn-accessibility-subtree">accessibility subtree</a> descendants
have roles limited to:
<a class="core-mapping" href="#role-map-generic">`generic`</a>,
<a class="core-mapping" href="#role-map-group">`group`</a>,
<a class="core-mapping" href="#role-map-paragraph">`paragraph`</a>,
<a class="core-mapping" href="#role-map-img">`img`</a>,
<a class="core-mapping" href="#role-map-none">`none`</a>,
or text.
</p>
<p>
Elements that contain any <a class="termref" data-cite="wai-aria-1.2#dfn-accessibility-subtree">accessibility subtree</a>
descendants with roles other than those listed above are considered to contain <dfn id="dfn-rich-content">rich content</dfn>.
This includes interactive elements (such as buttons, links, or form controls), semantic structures (such as tables, lists, or headings),
and landmark regions.
</p>
</section>
<section>
<h3>HTML Element Role Mappings</h3>
<ul>
Expand Down Expand Up @@ -9346,19 +9366,30 @@ <h4 id="att-command-popovers">`command` <span class="att-context">(in the Toggle
</th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
<span class="type">Relations:</span>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, `IA2_RELATION_DESCRIBED_BY`;
otherwise `IA2_RELATION_DETAILS` points to popover element.
<a href="#att-command-popovers-comments">See Comments</a>.
<div class="objattrs"><span class="type">Object attributes:</span> `details-roles:popover`</div>
</td>
</tr>
<tr>
<th><a href="https://msdn.microsoft.com/en-us/library/ms726297%28v=VS.85%29.aspx">UIA</a></th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, a described-by relation;
otherwise a details relation is made with the popover element.
<a href="#att-command-popovers-comments">See Comments</a>.
</td>
</tr>
<tr>
<th><a href="https://gnome.pages.gitlab.gnome.org/atk/">ATK</a></th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
<span class="type">Relations:</span>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, `RELATION_DESCRIBED_BY`;
otherwise `RELATION_DETAILS` points to popover element.
<a href="#att-command-popovers-comments">See Comments</a>.
<div class="objattrs"><span class="type">Object attributes:</span> `details-roles:popover`</div>
</td>
</tr>
Expand All @@ -9369,16 +9400,19 @@ <h4 id="att-command-popovers">`command` <span class="att-context">(in the Toggle
</td>
</tr>
<tr>
<th>Comments</th>
<th id="att-command-popovers-comments">Comments</th>
<td>
<p>
User Agents MUST expose an <a class="core-mapping" href="#ariaDetails">`aria-details`</a> relationship with the associated element (identified via the specified `commandfor`
User Agents MUST expose a relation with the associated element (identified via the specified `commandfor`
attribute) <strong>except</strong> under the following conditions:
</p>
<ul>
<li>The associated popover element is the next immediate accessibility sibling to the invoking element,</li>
<li>The element is a descendant of the `popover` it is associated with.</li>
</ul>
<p>
Author-provided `aria-describedby` or `aria-details` attributes on the invoking element take precedence over these implicit relations.
</p>
<p class="note">
A button that represents a <a data-cite="html/forms.html#concept-submit-button">submit button</a> or is in the
<a data-cite="html/input.html#reset-button-state-(type=reset)">reset state</a> with a [=button/form owner=] cannot invoke a command.
Expand Down Expand Up @@ -13645,7 +13679,10 @@ <h4 id="att-popover">`popover`</h4>
<a href="https://msdn.microsoft.com/en-us/library/dd373608%28v=VS.85%29.aspx">MSAA</a> + <a href="http://accessibility.linuxfoundation.org/a11yspecs/ia2/docs/html/">IAccessible2</a>
</th>
<td>
<span class="type">Relations:</span> `IA2_RELATION_DETAILS_FOR` points to invoking element. <a href="#att-popover-comments">See Comments</a>.
<span class="type">Relations:</span>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, `IA2_RELATION_DESCRIPTION_FOR`;
otherwise `IA2_RELATION_DETAILS_FOR` points to invoking element.
<a href="#att-popover-comments">See Comments</a>.
<div class="objattrs">
<span class="type">Object attributes:</span>
<code>ispopup: &lt;value></code> where <code>&lt;value></code> reflects the <a data-cite="html/popover.html#the-popover-attribute">popover</a> type.
Expand All @@ -13655,14 +13692,18 @@ <h4 id="att-popover">`popover`</h4>
<tr>
<th><a href="https://msdn.microsoft.com/en-us/library/ms726297%28v=VS.85%29.aspx">UIA</a></th>
<td>
A details relation is made with the invoking element, if an invoking element exists which meets the conditions for necessitating a details relationship.
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, a described-by relation;
otherwise a details relation is made with the invoking element.
<a href="#att-popover-comments">See Comments</a>.
</td>
</tr>
<tr>
<th><span class="informative">[[ATK]]</span></th>
<td>
<p><span class="type">Relations:</span> `RELATION_DETAILS_FOR` points to invoking element. <a href="#att-popover-comments">See Comments</a>.</p>
<span class="type">Relations:</span>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, `RELATION_DESCRIPTION_FOR`;
otherwise `RELATION_DETAILS_FOR` points to invoking element.
<a href="#att-popover-comments">See Comments</a>.
<div class="objattrs">
<span class="type">Object attributes:</span>
<code>ispopup: &lt;value></code> where <code>&lt;value></code> reflects the <a data-cite="html/popover.html#the-popover-attribute">popover</a> type.
Expand All @@ -13679,7 +13720,7 @@ <h4 id="att-popover">`popover`</h4>
<tr>
<th id="att-popover-comments">Comments</th>
<td>
<p>User agents MUST NOT expose a details relation between a `popover` and its invoking element under the following conditions:</p>
<p>User agents MUST NOT expose a relation between a `popover` and its invoking element under the following conditions:</p>
<ul>
<li>when the `popover` is the next immediate accessibility sibling to the invoking element,</li>
<li>when the element has a `popovertargetaction=hide` attribute value,</li>
Expand All @@ -13689,10 +13730,6 @@ <h4 id="att-popover">`popover`</h4>
If specified on an element with an implicit role of `generic`, then the element's role instead maps to <a class="core-mapping" href="#role-map-group">`group`</a> for all
<a data-cite="html/popover.html#the-popover-attribute">`popover` states</a>.
</p>
<p class="note">
There are no unique mappings for the different `popover` states. Any accessibility mapping changes for the popover element would be the responsibility of the author. e.g., using
different base HTML elements, attributes, or ARIA attributes to make such changes.
</p>
</td>
</tr>
</tbody>
Expand Down Expand Up @@ -13737,19 +13774,30 @@ <h4 id="att-popovertarget">`popovertarget`</h4>
</th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
<span class="type">Relations:</span>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, `IA2_RELATION_DESCRIBED_BY`;
otherwise `IA2_RELATION_DETAILS` points to popover element.
<a href="#att-popovertarget-comments">See Comments</a>.
<div class="general"><span class="type">Object attributes:</span> `details-roles:popover`</div>
</td>
</tr>
<tr>
<th><a href="https://msdn.microsoft.com/en-us/library/ms726297%28v=VS.85%29.aspx">UIA</a></th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, a described-by relation;
otherwise a details relation is made with the popover element.
<a href="#att-popovertarget-comments">See Comments</a>.
</td>
</tr>
<tr>
<th><span class="informative">[[ATK]]</span></th>
<td>
<div class="general">Use WAI-ARIA mapping</div>
<span class="type">Relations:</span>
If <a data-cite="html/popover.html#attr-popover-hint-state">`popover=hint`</a> with <a href="#dfn-plain-content">plain content</a>, `RELATION_DESCRIBED_BY`;
otherwise `RELATION_DETAILS` points to popover element.
<a href="#att-popovertarget-comments">See Comments</a>.
<div class="general"><span class="type">Object attributes:</span> `details-roles:popover`</div>
</td>
</tr>
Expand All @@ -13760,18 +13808,20 @@ <h4 id="att-popovertarget">`popovertarget`</h4>
</td>
</tr>
<tr>
<th>Comments</th>
<th id="att-popovertarget-comments">Comments</th>
<td>
<p>
User Agents MUST expose an <a class="core-mapping" href="#ariaDetails">`aria-details`</a> relation with the associated popover element <strong>except</strong> under the following
conditions:
User Agents MUST expose a relation with the associated popover element <strong>except</strong> under the following conditions:
</p>
<ul>
<li>The element's `popovertargetaction` attribute value is "`hide`"</li>
<li>The associated popover element is the next immediate accessibility sibling to the invoking element,</li>
<li>The element's implicit or explicit `popovertargetaction` is the "`auto`" state and the element is a descendant of the `popover` it is associated with.</li>
<!-- accessibility sibling will be defined in the ARIA specification -->
</ul>
<p>
Author-provided `aria-describedby` or `aria-details` attributes on the invoking element take precedence over these implicit relations.

@scottaohara scottaohara Jan 26, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

we may want to mention that even if they resolve to the empty string or result in no associated details relation (e.g., aria-details="").

i remember talking a lot about this with aaron, and how to allow for people to opt out of an automatic description/details relation, if they needed to.

this comment applies to other instances of this text in this PR

</p>
<p class="note">A button that represents a <a data-cite="html/forms.html#concept-submit-button">submit button</a> with a [=button/form owner=] cannot invoke a popover.</p>
</td>
</tr>
Expand Down