Skip to content

Add aria-actions focus handling wording #2845

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
smhigley wants to merge 1 commit into
base: secondary-actions
Choose a base branch
from
Open

Add aria-actions focus handling wording #2845

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 6 additions & 1 deletion core-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6461,7 +6461,12 @@ <h4>Not Mapped</h4>
</p>
</section>
<h4 id="ariaActions"><code>aria-actions</code></h4>
<table aria-labelledby="ariaActions">
<p>
After an action is invoked, browsers MUST NOT fire the API's <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.

@cookiecrook cookiecrook Jul 20, 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.

Suggested change
After an action is invoked, browsers MUST NOT fire the API's <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.
After an action is invoked, browsers SHOULD NOT fire the system or accessibility-specific <a href="#focus_state_event_table">focus event</a> when the referenced action node receives focus.

@cookiecrook cookiecrook Jul 20, 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.

Also I think this should be focus "Notification" or "Signals" rather than "Events"? My understanding is that, for most native platform APIs "Event" is referring to an input event like a click (most often user-triggered), but the subsequent broadcasts that goes out over the system would be called "Notifications" on Windows and Apple systems, or "Signals" on GTK.

@janewman janewman Jul 24, 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.

I don't have a strong preference here but wanted to note that core-aam already uses the term "Focus event" for these platform mappings. If we want to use "Notification" or "Signals" instead, we should change this everywhere for consistency.

The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>,

@cookiecrook cookiecrook Jul 21, 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.

"subsequently" may be too vague here. does this happen in the same runloop? If not, how long could/should an implementation wait before it's non-compliant?

@cookiecrook cookiecrook Jul 21, 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.

Also, same issue as above wrt "event" vs "notification" and "system or accessibility-specific" vs "API"

@mcking65 mcking65 Aug 10, 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.

There should not be a comma before the word 'unless':

Suggested change
The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>,
The browser MUST subsequently return DOM focus to the referencing node also without firing an API <a href="#focus_state_event_table">focus event</a>

unless focus is moved to a different node by a programmatic focus change or a user interaction.
</p>
<table class="data" aria-labelledby="ariaActions">
<tbody>
<tr>
<th>ARIA Specification</th>
Expand Down
15 changes: 14 additions & 1 deletion index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12197,8 +12197,21 @@ <h2>Definitions of States and Properties (all aria-* attributes)</h2>
<li>User Agents SHOULD use the accessible names of elements referenced by <code>aria-actions</code> to determine the names of actions that are exposed in a platform accessibility API.</li>
<li>User Agents MUST NOT expose <code>aria-actions</code> if the Author MUST's are not followed.</li>
</ul>
<p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:</p>

@cookiecrook cookiecrook Jul 21, 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.

Suggested change
<p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST do the following steps to manage focus once an action is invoke via the <code>aria-actions</code> API:</p>
<p>In order to allow users to invoke actions while remaining on the referencing element, browsers MUST perform the following steps to manage focus once an action is invoked via <code>aria-actions</code>:</p>

@cookiecrook cookiecrook Jul 21, 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.

In addition to the first two editorial diffs here, I wasn't sure "the aria-actions API" sounded quite right to me. I'm not set on that final diff through if you want it back.

@mcking65 mcking65 Aug 10, 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.

Suggested change:

            <p>To prevent unexpected focus change away from the referencing element after users invoke actions, browsers MUST perform the following steps to manage focus once an action is invoked via <code>aria-actions</code>:</p>

@mcking65 mcking65 Aug 10, 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.

I suggest changing the initial phrase to clarify both:

  1. that the user is not on the referencing element, the focus is on the referencing element.
  2. The intent is to maintain focus after the action is invoked if doing so is xpected.

<ol>
<li>
If the referenced action node is focusable and receives focus as a result of an <code>aria-actions</code> invocation:

@mcking65 mcking65 Aug 10, 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.

Suggested change
If the referenced action node is focusable and receives focus as a result of an <code>aria-actions</code> invocation:
If the referenced action node is focusable and received focus as a result of an <code>aria-actions</code> invocation:

<ul>
<li>Allow the DOM focus events to fire on the referenced action node as a result of invoking it.</li>
<li>Do not fire the <a>desktop focus event</a>.</li>

@cookiecrook cookiecrook Jul 21, 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.

Suggested change
<li>Do not fire the <a>desktop focus event</a>.</li>
<li>Do not fire the <a>system or accessibility-specific focus notification</a>.</li>

Caveat: keep this in line with whatever prose decision is made above on this same issue.

@smhigley smhigley Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

this one was a bit on purpose, since the wording "desktop focus event" is used for this elsewhere in the spec & there's a definition for it as well

</ul>
</li>
<li>If focus is moved either programmatically or via a user interaction, handle that focus change as normal, and do not perform any further <code>aria-actions</code> focus steps.</li>

@cookiecrook cookiecrook Jul 21, 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.

If focus is moved either programmatically or via a user interaction,

I presume you're not counting an aria-actions invocation here as a "user interaction" so I would recommend a different term that more clearly excludes it.

handle that focus change as normal

Is there language in the HTML or DOM specs that phrases these more precisely?

@smhigley smhigley Jul 23, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

I think if a second aria-actions invocation happened here, then presumably this set of focus steps should be abandoned and that aria-actions focus behavior should be kicked off, so I think it still applies 😅

Still open to better or more precise wording in both cases though

<li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>

@cookiecrook cookiecrook Jul 21, 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.

But focus did move to get here, right? So the "if focus has not moved" clause would never be invoked.

ditto prose for "desktop focus event" (these notifications also aren't limited to "desktops")

@smhigley smhigley Jul 23, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

This is the spec definition for "desktop focus event", should we change the wording or add an additional term that shares the same def?

Event from/to the host operating system via the accessibility API, notifying of a change of input focus.

@mcking65 mcking65 Aug 10, 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.

Suggested change
<li>If focus has not moved, the browser MUST move DOM focus back to the referencing element, again without firing a <a>desktop focus event</a>.</li>
<li>If the referenced action node is focusable and received focus, move DOM focus back to the referencing element without firing a <a>desktop focus event</a>.</li>

@mcking65 mcking65 Aug 10, 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.

This list item needs the same 'if' condition as the first list item. It does not need to state that it is the result of the action invocation or that the browser must do the focus change because those things are stated before the start of the list.

<li>If the referencing element can no longer be focused, the browser MAY keep focus on the referenced action element and fire a <a>desktop focus event</a>.</li>

@cookiecrook cookiecrook Jul 21, 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.

ditto

</ol>
</div>
<table class="property-features">
<table class="def">
<caption>Characteristics:</caption>
<thead>
<tr>
Expand Down
Loading