Skip to content

Commit 5c7229a

Browse files
janewmankeithamuspkraspectranautsmockle
authored
Add ariaNotify (#2577)
This adds the mechanics for introducing the ariaNotify API on Elements, which is a function that will map to various AT APIs, as defined in core-aam. Co-authored-by: Keith Cirkel <keithamus@users.noreply.github.com> Co-authored-by: pkra <pkra@users.noreply.github.com> Co-authored-by: Valerie Young <spectranaut@igalia.com> Co-authored-by: Clay Miller <clay@smockle.com>
1 parent 27b1f2b commit 5c7229a

2 files changed

Lines changed: 177 additions & 3 deletions

File tree

‎core-aam/index.html‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12444,6 +12444,132 @@ <h3>Special Events for Menus</h3>
1244412444
</section>
1244512445
</section>
1244612446

12447+
<section id="mapping_algorithms">
12448+
<h2>Algorithms</h2>
12449+
<p>
12450+
Some <abbr title="Application Programming Interfaces">APIs</abbr> provide
12451+
methods which require specific algorithms to be followed. The following
12452+
sections provide the algorithm mapping tables for these methods.
12453+
</p>
12454+
<h3>ARIANotifyMixin Algorithm Mapping Tables</h3>
12455+
<p>
12456+
The <code>ARIANotifyMixin</code> provides a method for announcing content
12457+
to assistive technologies. The following algorithm mappings specify how
12458+
these announcements will be implemented across different accessibility
12459+
APIs to ensure consistent behavior for users of assistive technologies.
12460+
</p>
12461+
<h4 id="arianotifymixin-map-arianotify">ariaNotify</h4>
12462+
<p>To <code>aria notify</code> given <var>node</var>, <var>announcement</var>, and <var>priority</var>:</p>
12463+
<table aria-labelledby="arianotifymixin-map-arianotify" class="data">
12464+
<tbody>
12465+
<tr>
12466+
<th>ARIA Specification</th>
12467+
<td>
12468+
<a class="method-reference" href="#arianotify"><code>aria notify</code></a>
12469+
</td>
12470+
</tr>
12471+
<tr>
12472+
<th>Preconditions</th>
12473+
<td>
12474+
<p>If <var>node</var> is <a class="specref" href="#tree_exclusion">excluded from the accessibility tree</a>, then abort these steps.</p>
12475+
</td>
12476+
</tr>
12477+
<tr>
12478+
<th>Language</th>
12479+
<td>
12480+
<p>
12481+
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:
12482+
</p>
12483+
<ol>
12484+
<li>The <var>node</var>'s nearest ancestor element's <code>lang</code> attribute.</li> (including <var>node</var> itself)
12485+
<li>The document element's <code>lang</code> attribute.</li> (including when called on the document).
12486+
<li>A user agent or platform default.</li>
12487+
</ol>
12488+
<p>
12489+
Assistive technologies MUST present the announcement using that language (for example, voice, pronunciation rules, braille table).
12490+
</p>
12491+
</td>
12492+
</tr>
12493+
<tr>
12494+
<th>MSAA + IAccessible2</th>
12495+
<td>
12496+
<p>No implementation specified (<a href="#arianotify-fallback-note">see fallback note</a>).</p>
12497+
</td>
12498+
</tr>
12499+
<tr>
12500+
<th><abbr title="User Interface Automation">UIA</abbr></th>
12501+
<td>
12502+
<ol>
12503+
<li>
12504+
<p>Let <var>mapped_priority</var> be <code>NotificationProcessing_ImportantAll</code> if <var>priority</var> is "high", otherwise <code>NotificationProcessing_All</code>.</p>
12505+
</li>
12506+
<li>
12507+
<p>
12508+
Call <code>UiaRaiseNotificationEvent</code> with <var>node</var>, <code>NotificationKind_ActionCompleted</code>, <var>mapped_priority</var>, <var>announcement</var>, and the empty
12509+
string.
12510+
</p>
12511+
</li>
12512+
</ol>
12513+
<p class="note">
12514+
If the platform accessibility implementation determines that <var>node</var> is not represented in the UIA
12515+
<a href="https://learn.microsoft.com/en-us/windows/win32/winauto/uiauto-treeoverview#control-view">Control view</a> or
12516+
<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
12517+
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
12518+
in one of these views) to ensure assistive technologies that ignore events on elements not in the Control or Content view receive the notification.
12519+
</p>
12520+
</td>
12521+
</tr>
12522+
<tr>
12523+
<th><abbr title="Accessibility Toolkit">ATK</abbr></th>
12524+
<td>
12525+
<ol>
12526+
<li>
12527+
<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>
12528+
</li>
12529+
<li>
12530+
<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>
12531+
</li>
12532+
</ol>
12533+
<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>
12534+
</td>
12535+
</tr>
12536+
<tr>
12537+
<th><abbr title="Assistive Technology - Service Provider Interface">AT-SPI</abbr></th>
12538+
<td>
12539+
<ol>
12540+
<li>
12541+
<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>
12542+
</li>
12543+
<li>
12544+
<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>
12545+
</li>
12546+
</ol>
12547+
</td>
12548+
</tr>
12549+
<tr>
12550+
<th><abbr title="macOS Accessibility Protocol">AX API</abbr></th>
12551+
<td>
12552+
<ol>
12553+
<li>
12554+
<p>Let <var>mapped_priority</var> be <code>NSAccessibilityPriorityHigh</code> if <var>priority</var> is "high", otherwise <code>NSAccessibilityPriorityMedium</code>.</p>
12555+
</li>
12556+
<li>
12557+
<p>Let <var>userInfo</var> be a <code>NSDictionary</code> with the following keys:</p>
12558+
<ol>
12559+
<li><code>NSAccessibilityAnnouncementKey</code> as <var>announcement</var></li>
12560+
<li><code>NSAccessibilityPriorityKey</code> as <var>mapped_priority</var></li>
12561+
</ol>
12562+
</li>
12563+
<li>
12564+
<p>Call <code>NSAccessibilityPostNotificationWithUserInfo</code> with <var>node</var>, <var>NSAccessibilityAnnouncementRequestedNotification</var>, and <var>userInfo</var>.</p>
12565+
</li>
12566+
</ol>
12567+
</td>
12568+
</tr>
12569+
</tbody>
12570+
</table>
12571+
<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>
12572+
</section>
1244712573
<section>
1244812574
<h2>Privacy considerations</h2>
1244912575
<p>

‎index.html‎

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@
172172

173173
preProcess: [linkCrossReferences, getParticipants],
174174
postProcess: [ariaAttributeReferences],
175-
xref: ["dom", "accname-1.2", "core-aam-1.2", "infra", "HTML"],
175+
xref: ["dom", "accname-1.2", "core-aam-1.2", "infra", "HTML", "permissions-policy"],
176176
definitionMap: [],
177177
};
178178
function respecChangelogFilter(commit) {
@@ -16746,8 +16746,8 @@ <h3>Presentational Roles Conflict Resolution</h3>
1674616746
</section>
1674716747
</section>
1674816748
<section id="idl-interface" class="normative">
16749-
<h2>IDL Interface</h2>
16750-
<p>Conforming user agents MUST implement the following IDL interface.</p>
16749+
<h2>IDL Interfaces</h2>
16750+
<p>Conforming user agents MUST implement the following IDL interfaces.</p>
1675116751
<section id="ARIAMixin" class="normative" data-dfn-for="ARIAMixin" data-link-for="ARIAMixin">
1675216752
<h2>Interface Mixin <dfn>ARIAMixin</dfn></h2>
1675316753
<pre class="idl" data-cite="webidl">
@@ -16809,6 +16809,54 @@ <h2>Interface Mixin <dfn>ARIAMixin</dfn></h2>
1680916809
</pre
1681016810
>
1681116811
</section>
16812+
<section id="ARIANotifyMixin" class="normative" data-dfn-for="ARIANotifyMixin" data-link-for="ARIANotifyMixin">
16813+
<h2>Interface Mixin <dfn>ARIANotifyMixin</dfn></h2>
16814+
<pre class="idl" data-cite="webidl">
16815+
enum AriaNotifyPriority { "normal", "high" };
16816+
16817+
dictionary AriaNotificationOptions {
16818+
AriaNotifyPriority priority = "normal";
16819+
};
16820+
interface mixin ARIANotifyMixin {
16821+
undefined ariaNotify(DOMString announcement, optional AriaNotificationOptions options = {});
16822+
};
16823+
Element includes ARIANotifyMixin;
16824+
Document includes ARIANotifyMixin;
16825+
</pre>
16826+
16827+
<p>
16828+
The User Agent processing steps for the
16829+
<code><dfn method for="ARIANotifyMixin" >ariaNotify</dfn>(<var>announcement</var>, <var>options</var>)</code>
16830+
method are:
16831+
</p>
16832+
<ol>
16833+
<li>
16834+
<p>If the document is not [=allowed to use=] the feature identified by <a>"aria-notify"</a> abort these steps.</p>
16835+
</li>
16836+
<li>
16837+
<p>Let <var>node</var> be <code>this</code>.</p>
16838+
</li>
16839+
<li>
16840+
<p>Let <var>priority</var> be <var>options</var>["<code><a href="#dom-arianotificationoptions-priority">priority</a></code>"].</p>
16841+
</li>
16842+
<li>
16843+
<p>If <var>node</var> is <a href="#tree_exclusion">excluded from the accessibility tree</a>, then abort these steps.</p>
16844+
</li>
16845+
<li>
16846+
<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>
16847+
</li>
16848+
</ol>
16849+
16850+
<section id="arianotify-permissions-policy">
16851+
<h3>Permissions Policy Integration</h3>
16852+
<p>This specification defines a [=policy-controlled feature=] identified by the string <code><dfn class="permission">"aria-notify"</dfn></code>.
16853+
It has a [=policy-controlled feature/default allowlist=] of <code class=permissionspolicy>"*"</code>.
16854+
</p>
16855+
<p class="note">
16856+
When disabled in a document, any notifications applied using <code>ariaNotify</code> within that document will not be sent.
16857+
</p>
16858+
</section>
16859+
</section>
1681216860

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

0 commit comments

Comments
 (0)