Skip to content

Add ariaNotify #2577

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 31 commits into
base: main
Choose a base branch
from
+177 −3
Open

Add ariaNotify #2577

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
31 commits
Select commit Hold shift + click to select a range
31c988a
add arianotify draft
keithamus May 23, 2024
f7cf965
add arianotify draft
keithamus May 23, 2024
582c912
chore: prettier
pkra Mar 13, 2025
8b5987e
rework to newest iteration of v1 proposla
keithamus Mar 20, 2025
20c0da4
chore: prettier
keithamus Mar 20, 2025
83c2d1b
avoid "should"
keithamus Mar 20, 2025
394b946
s/iua/uia/
keithamus Mar 20, 2025
f7e58ed
Update aria notify section with permissions policy section.
janewman Jul 14, 2025
c13cd7d
Update disabled wording in the note.
janewman Jul 15, 2025
01504b0
Add xref for permissions-policy
janewman Jul 15, 2025
42ab8b2
Update how permissions policy will impact the method steps.
janewman Jul 15, 2025
586864a
Fill in missing details and fix references.
janewman Jul 16, 2025
e8d4f58
Merge branch 'main' into aria-notify-draft-additions
janewman Jul 16, 2025
b80fa36
replace should with 'will'
janewman Jul 29, 2025
a61fd59
Update core-aam/index.html
janewman Aug 15, 2025
e154e3b
Editorial fixes. Update note for fallback mechanism.
janewman Aug 15, 2025
f3e8781
Add non-normative reccomendation for assitive technologies to impleme…
janewman Aug 15, 2025
e08170f
Add context and strengthen suggestion for assistive technologies.
janewman Aug 19, 2025
2f1aff0
Update core-aam/index.html
janewman Aug 19, 2025
1bb17ff
Update core-aam/index.html
janewman Aug 19, 2025
d318c00
Add clarity on node/this.
janewman Aug 20, 2025
02a2644
Add requirement for the node to be exposed to the accessibility tree.
janewman Aug 25, 2025
0085ba4
Reference existing spec for excluding nodes.
janewman Aug 25, 2025
90e4ccb
Remove reccomendation for ATs to allow history, this will be tracked …
janewman Aug 26, 2025
665b82c
Add note for bubbling the UIA notification out of a element not in th…
janewman Aug 26, 2025
446f27c
remove body-specific note on UIA implementation.
janewman Aug 26, 2025
a011a02
Link priority to the priority IDL.
janewman Aug 28, 2025
f4a2232
Add language section.
janewman Aug 28, 2025
a056c26
Update AX API section to use the node, rather than the associated win…
janewman Aug 28, 2025
3d181f9
Merge branch 'main' into aria-notify-draft-additions
keithamus Sep 2, 2025
3972a86
Update core-aam/index.html
janewman Sep 3, 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
126 changes: 126 additions & 0 deletions core-aam/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11199,6 +11199,132 @@ <h3>Special Events for Menus</h3>
</section>
</section>

<section id="mapping_algorithms">
<h2>Algorithms</h2>
<p>
Some <abbr title="Application Programming Interfaces">APIs</abbr> provide
methods which require specific algorithms to be followed. The following
sections provide the algorithm mapping tables for these methods.
</p>
<h3>ARIANotifyMixin Algorithm Mapping Tables</h3>
<p>
The <code>ARIANotifyMixin</code> provides a method for announcing content
to assistive technologies. The following algorithm mappings specify how
these announcements will be implemented across different accessibility
APIs to ensure consistent behavior for users of assistive technologies.
</p>
<h4 id="arianotifymixin-map-arianotify">ariaNotify</h4>
<p>To <code>aria notify</code> given <var>node</var>, <var>announcement</var>, and <var>priority</var>:</p>
<table aria-labelledby="arianotifymixin-map-arianotify" class="data">
<tbody>
<tr>
<th>ARIA Specification</th>
<td>
<a class="method-reference" href="#arianotify"><code>aria notify</code></a>
</td>
</tr>
<tr>
<th>Preconditions</th>
<td>
<p>If <var>node</var> is <a class="specref" href="#tree_exclusion">excluded from the accessibility tree</a>, then abort these steps.</p>
</td>
</tr>
<tr>
<th>Language</th>
<td>
<p>
User agents and assistive technologies MUST determine the language of the announcement by taking the first valid BCP&nbsp;47 language tag from the following sources:
Copy link
Contributor

@smockle smockle Sep 3, 2025

Choose a reason for hiding this comment

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

Non-blocking: Would it be useful to link to a definition of “BCP 47 language tag”?

I looked for something we could xref with respec, but https://respec.org/xref/?term=BCP+47 returns no results.

</p>
<ol>
<li>The <var>node</var>'s nearest ancestor element's <code>lang</code> attribute.</li> (including <var>node</var> itself)
<li>The document element's <code>lang</code> attribute.</li> (including when called on the document).
<li>A user agent or platform default.</li>
</ol>
<p>
Assistive technologies MUST present the announcement using that language (for example, voice, pronunciation rules, braille table).
</p>
</td>
</tr>
<tr>
<th>MSAA + IAccessible2</th>
<td>
<p>No implementation specified (<a href="#arianotify-fallback-note">see fallback note</a>).</p>
</td>
</tr>
<tr>
<th><abbr title="User Interface Automation">UIA</abbr></th>
<td>
<ol>
<li>
<p>Let <var>mapped_priority</var> be <code>NotificationProcessing_ImportantAll</code> if <var>priority</var> is "high", otherwise <code>NotificationProcessing_All</code>.</p>
</li>
<li>
<p>
Call <code>UiaRaiseNotificationEvent</code> with <var>node</var>, <code>NotificationKind_ActionCompleted</code>, <var>mapped_priority</var>, <var>announcement</var>, and the empty
string.
</p>
</li>
</ol>
<p class="note">
If the platform accessibility implementation determines that <var>node</var> is not represented in the UIA
<a href="https://learn.microsoft.com/en-us/windows/win32/winauto/uiauto-treeoverview#control-view">Control view</a> or
<a href="https://learn.microsoft.com/en-us/windows/win32/winauto/uiauto-treeoverview#content-view">Content view</a>, user agents SHOULD instead raise the notification event
on the nearest ancestor that is represented as a UIA Control. If no such ancestor exists, user agents SHOULD raise it on the document root (which is expected to be
in one of these views) to ensure assistive technologies that ignore events on elements not in the Control or Content view receive the notification.
</p>
</td>
</tr>
<tr>
<th><abbr title="Accessibility Toolkit">ATK</abbr></th>
<td>
<ol>
<li>
<p>Let <var>mapped_priority</var> be <code>Atk.Live.ATK_LIVE_ASSERTIVE</code> if <var>priority</var> is "high", otherwise <code>Atk.Live.ATK_LIVE_POLITE</code>.</p>
</li>
<li>
<p>Call <code>g_signal_emit_by_name</code> with <var>node</var>, <code>"notification"</code>, <var>announcement</var>, and <var>mapped_priority</var>.</p>
</li>
</ol>
<p>On older Linux accessibility stacks prior to ATK 2.50.0, user agents MAY use the fallback; <a href="#arianotify-fallback-note">see fallback note</a>.</p>
</td>
</tr>
<tr>
<th><abbr title="Assistive Technology - Service Provider Interface">AT-SPI</abbr></th>
<td>
<ol>
<li>
<p>Let <var>mapped_priority</var> be <code>ATSPI_LIVE_ASSERTIVE</code> if <var>priority</var> is "high", otherwise <code>ATSPI_LIVE_POLITE</code>.</p>
</li>
<li>
<p>Send a DBUS signal <code>ATSPI_DBUS_INTERFACE_EVENT_OBJECT</code> with <var>node</var>, <code>"announcement"</code>, <var>announcement</var>, and <var>mapped_priority</var>.</p>
</li>
</ol>
</td>
</tr>
<tr>
<th><abbr title="macOS Accessibility Protocol">AX API</abbr></th>
<td>
<ol>
<li>
<p>Let <var>mapped_priority</var> be <code>NSAccessibilityPriorityHigh</code> if <var>priority</var> is "high", otherwise <code>NSAccessibilityPriorityMedium</code>.</p>
</li>
<li>
<p>Let <var>userInfo</var> be a <code>NSDictionary</code> with the following keys:</p>
<ol>
<li><code>NSAccessibilityAnnouncementKey</code> as <var>announcement</var></li>
<li><code>NSAccessibilityPriorityKey</code> as <var>mapped_priority</var></li>
</ol>
</li>
<li>
<p>Call <code>NSAccessibilityPostNotificationWithUserInfo</code> with <var>node</var>, <var>NSAccessibilityAnnouncementRequestedNotification</var>, and <var>userInfo</var>.</p>
</li>
</ol>
</td>
</tr>
</tbody>
</table>
<p id="arianotify-fallback-note" class="note">When no suitable platform notification API is available (for example, older Linux accessibility stacks prior to ATK 2.50.0 that lack the newer notification signal, or on Windows when the user agent is not able to use UIA), a user agent MAY synthesize a temporary, assistive-technology-only live region in its accessibility tree to convey an <code>aria notify</code> announcement. Such fallback nodes are not exposed to or detectable by web content and this behavior is not required.</p>
</section>
<section>
<h2>Privacy considerations</h2>
<p>
Expand Down
54 changes: 51 additions & 3 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -179,7 +179,7 @@

preProcess: [linkCrossReferences, getParticipants],
postProcess: [ariaAttributeReferences],
xref: ["dom", "accname-1.2", "core-aam-1.2", "infra", "HTML"],
xref: ["dom", "accname-1.2", "core-aam-1.2", "infra", "HTML", "permissions-policy"],
definitionMap: [],
};
function respecChangelogFilter(commit) {
Expand Down Expand Up @@ -16733,8 +16733,8 @@ <h3>Presentational Roles Conflict Resolution</h3>
</section>
</section>
<section id="idl-interface" class="normative">
<h2>IDL Interface</h2>
<p>Conforming user agents MUST implement the following IDL interface.</p>
<h2>IDL Interfaces</h2>
<p>Conforming user agents MUST implement the following IDL interfaces.</p>
<section id="ARIAMixin" class="normative" data-dfn-for="ARIAMixin" data-link-for="ARIAMixin">
<h2>Interface Mixin <dfn>ARIAMixin</dfn></h2>
<pre class="idl" data-cite="webidl">
Expand Down Expand Up @@ -16797,6 +16797,54 @@ <h2>Interface Mixin <dfn>ARIAMixin</dfn></h2>
>

</section>
<section id="ARIANotifyMixin" class="normative" data-dfn-for="ARIANotifyMixin" data-link-for="ARIANotifyMixin">
<h2>Interface Mixin <dfn>ARIANotifyMixin</dfn></h2>
<pre class="idl" data-cite="webidl">
enum AriaNotifyPriority { "normal", "high" };

dictionary AriaNotificationOptions {
AriaNotifyPriority priority = "normal";
};
interface mixin ARIANotifyMixin {
undefined ariaNotify(DOMString announcement, optional AriaNotificationOptions options = {});
};
Element includes ARIANotifyMixin;
Document includes ARIANotifyMixin;
</pre>

<p>
The User Agent processing steps for the
<code><dfn method for="ARIANotifyMixin" >ariaNotify</dfn>(<var>announcement</var>, <var>options</var>)</code>
method are:
</p>
<ol>
<li>
<p>If the document is not [=allowed to use=] the feature identified by <a>"aria-notify"</a> abort these steps.</p>
</li>
<li>
<p>Let <var>node</var> be <code>this</code>.</p>
</li>
<li>
<p>Let <var>priority</var> be <var>options</var>["<code><a href="#dom-arianotificationoptions-priority">priority</a></code>"].</p>
</li>
<li>
<p>If <var>node</var> is <a href="#tree_exclusion">excluded from the accessibility tree</a>, then abort these steps.</p>
</li>
<li>
<p>Run the <a data-cite="core-aam-1.2#arianotify">aria notify steps</a> given <var>node</var>, <var>announcement</var>, and <var>priority</var>.</p>
</li>
</ol>

<section id="arianotify-permissions-policy">
<h3>Permissions Policy Integration</h3>
<p>This specification defines a [=policy-controlled feature=] identified by the string <code><dfn class="permission">"aria-notify"</dfn></code>.
It has a [=policy-controlled feature/default allowlist=] of <code class=permissionspolicy>"*"</code>.
</p>
<p class="note">
When disabled in a document, any notifications applied using <code>ariaNotify</code> within that document will not be sent.
</p>
</section>
</section>

<section id="accessibilityroleandproperties-correspondence" class="normative" data-dfn-for="ARIAMixin" data-link-for="ARIAMixin">
<h2>ARIA Attribute Correspondence</h2>
Expand Down