A platform for community discussion. Free, open, simple.
A11Y: Idle live regions on a space so identical repeats are announced (#42184)
Sérgio Saquetim6389fffb6547
diff --git a/frontend/discourse/app/components/a11y/live-regions.gjs b/frontend/discourse/app/components/a11y/live-regions.gjsindex d4df9b906c6..faebcc5483d 100644--- a/frontend/discourse/app/components/a11y/live-regions.gjs+++ b/frontend/discourse/app/components/a11y/live-regions.gjs@@ -1,9 +1,37 @@import Component from "@glimmer/component";import { service } from "@ember/service";+/**+ * What the regions hold when there is nothing to say.+ *+ * A live region speaks when its text *changes*, and an empty one is not a reliable starting+ * point: announcing the same message twice in a row is inaudible on VoiceOver even though the+ * region is blanked and rewritten in between, because the text it ends up with is the text it+ * already had. Idling on a non-breaking space makes every transition a change between two+ * non-empty strings, which does get read — so a reader who keeps typing a query that keeps+ * matching nothing hears the outcome each time rather than once.+ *+ * A non-breaking space renders invisibly and is not announced on its own. Deliberately applied+ * here and not in the service, whose messages are the values callers compare announcements+ * against: a placeholder there makes "nothing is being announced" indistinguishable from a real+ * message, and every such comparison silently stops matching.+ *+ * Exported so a test asserting that a region said nothing can name this rather than spell out an+ * invisible character.+ */+export const IDLE_ANNOUNCEMENT = "\u00a0"; // non-breaking space+export default class A11yLiveRegions extends Component {@service a11y;+ get assertiveMessage() {+ return this.a11y.assertiveMessage || IDLE_ANNOUNCEMENT;+ }++ get politeMessage() {+ return this.a11y.politeMessage || IDLE_ANNOUNCEMENT;+ }+<template><divid="a11y-announcements-polite"@@ -12,7 +40,7 @@ export default class A11yLiveRegions extends Component {aria-live="polite"aria-atomic="true">- {{this.a11y.politeMessage}}+ {{this.politeMessage}}</div><divid="a11y-announcements-assertive"@@ -21,7 +49,7 @@ export default class A11yLiveRegions extends Component {aria-live="assertive"aria-atomic="true">- {{this.a11y.assertiveMessage}}+ {{this.assertiveMessage}}</div></template>}diff --git a/frontend/discourse/tests/acceptance/topic-unread-posts-announcement-test.js b/frontend/discourse/tests/acceptance/topic-unread-posts-announcement-test.jsindex 6555e3c6224..5fab8f9ca12 100644--- a/frontend/discourse/tests/acceptance/topic-unread-posts-announcement-test.js+++ b/frontend/discourse/tests/acceptance/topic-unread-posts-announcement-test.js@@ -1,6 +1,7 @@import { visit } from "@ember/test-helpers";import { test } from "qunit";import sinon from "sinon";+import { IDLE_ANNOUNCEMENT } from "discourse/components/a11y/live-regions";import { cloneJSON } from "discourse/lib/object";import { disableClearA11yAnnouncementsInTests } from "discourse/services/a11y";import topicFixtures from "discourse/tests/fixtures/topic";@@ -43,7 +44,10 @@ acceptance("Topic - unread posts announcement", function (needs) {assert.dom("#a11y-announcements-polite")- .hasText("", "no announcement without a last read post number");+ .hasText(+ IDLE_ANNOUNCEMENT,+ "no announcement without a last read post number"+ );});test("stays silent when the topic is fully read", async function (assert) {@@ -53,7 +57,10 @@ acceptance("Topic - unread posts announcement", function (needs) {assert.dom("#a11y-announcements-polite")- .hasText("", "no announcement when there are no unread posts");+ .hasText(+ IDLE_ANNOUNCEMENT,+ "no announcement when there are no unread posts"+ );});test("does not repeat while moving between posts of the same topic", async function (assert) {diff --git a/frontend/discourse/tests/integration/components/a11y/live-regions-test.gjs b/frontend/discourse/tests/integration/components/a11y/live-regions-test.gjsindex 7910c456c5b..fa8bc0b436d 100644--- a/frontend/discourse/tests/integration/components/a11y/live-regions-test.gjs+++ b/frontend/discourse/tests/integration/components/a11y/live-regions-test.gjs@@ -184,6 +184,58 @@ module("Integration | Component | A11y | LiveRegions", function (hooks) {);});+ // The reason the regions idle on a non-breaking space instead of on nothing. Blanking and+ // rewriting is enough for the DOM to record a change, but not for VoiceOver to speak one: it+ // compares what the region ends up saying with what it said before, and an empty middle state+ // leaves those identical. Idling on a character makes the middle state a real text — so a+ // reader who keeps typing a query that keeps matching nothing is told each time.+ //+ // The measure is "not whitespace-only", never "not empty". A region's text always carries the+ // template's own newlines and indentation, so an emptiness check passes whatever the component+ // renders — the first draft of this test did exactly that, and stayed green against a build+ // with no idle character at all. Ordinary whitespace collapses to nothing for a reader; a+ // non-breaking space is what survives, which is the whole reason it is the character chosen.+ REGIONS.forEach(({ type, selector }) => {+ test(`the ${type} region never falls silent, so an identical repeat is a change`, async function (assert) {+ disableClearA11yAnnouncementsInTests();+ await render(<template><A11yLiveRegions /></template>);++ const spoken = (text) => text.replace(/[\t\n\r ]+/g, "");+ const element = find(selector);+ assert.notStrictEqual(+ spoken(element.textContent),+ "",+ "a region with nothing to say still holds something a reader can notice leaving"+ );++ const a11y = getOwner(this).lookup("service:a11y");+ const seen = [];+ const observer = new MutationObserver(() =>+ seen.push(element.textContent)+ );+ observer.observe(element, {+ childList: true,+ characterData: true,+ subtree: true,+ });+ observers.push(observer);++ a11y.announce("no results", type);+ await settled();+ a11y.announce("no results", type);+ await settled();++ assert.true(+ seen.every((text) => spoken(text) !== ""),+ "and never falls silent on its way between two identical messages"+ );+ assert.true(+ seen.filter((text) => text.includes("no results")).length > 1,+ "so the second one is a text change rather than a rewrite of what was already there"+ );+ });+ });+test("a repeat already in flight is never spoken once a newer announcement arrives", async function (assert) {disableClearA11yAnnouncementsInTests();await render(<template><A11yLiveRegions /></template>);@@ -195,14 +247,19 @@ module("Integration | Component | A11y | LiveRegions", function (hooks) {const mutations = watchTextMutations("#a11y-announcements-polite");- // Advance one tick so the repeat has blanked the region but has not restored it yet.+ // Advance one tick so the repeat has cleared the region but has not restored it yet.// A newer announcement arriving in that window has to win outright: asserting only the// final text would miss the region speaking the stale message on the way there.+ // Asserted as the absence of the message rather than as an empty region: a cleared region+ // idles on a non-breaking space rather than on nothing — see `A11yLiveRegions`.a11y.announce("1 result", "polite");await new Promise((resolve) => next(resolve));assert.dom("#a11y-announcements-polite")- .hasNoText("the repeat blanks the region before restoring it");+ .doesNotIncludeText(+ "1 result",+ "the repeat clears the region before restoring it"+ );a11y.announce("2 results", "polite");await settled();diff --git a/plugins/chat/test/javascripts/components/chat-channel-announcements-test.gjs b/plugins/chat/test/javascripts/components/chat-channel-announcements-test.gjsindex 1764c077825..0a89b498290 100644--- a/plugins/chat/test/javascripts/components/chat-channel-announcements-test.gjs+++ b/plugins/chat/test/javascripts/components/chat-channel-announcements-test.gjs@@ -1,7 +1,9 @@import { getOwner } from "@ember/owner";import { render } from "@ember/test-helpers";import { module, test } from "qunit";-import A11yLiveRegions from "discourse/components/a11y/live-regions";+import A11yLiveRegions, {+ IDLE_ANNOUNCEMENT,+} from "discourse/components/a11y/live-regions";import {disableClearA11yAnnouncementsInTests,enableClearA11yAnnouncementsInTests,@@ -78,6 +80,8 @@ module(.hasText("otheruser: Hello there");});+ // A region with nothing to announce holds `IDLE_ANNOUNCEMENT`, not nothing: one that idles+ // empty cannot speak the same message twice — see `A11yLiveRegions`.test("does not announce the current user's own messages", async function (assert) {await render(<template>@@ -90,7 +94,9 @@ module(user: { id: this.currentUser.id, username: this.currentUser.username },});- assert.dom("#a11y-announcements-polite").hasNoText();+ assert+ .dom("#a11y-announcements-polite")+ .hasText(IDLE_ANNOUNCEMENT, "your own message is not announced to you");});test("does not announce messages from ignored users", async function (assert) {@@ -105,7 +111,12 @@ module(await publishSentMessage();- assert.dom("#a11y-announcements-polite").hasNoText();+ assert+ .dom("#a11y-announcements-polite")+ .hasText(+ IDLE_ANNOUNCEMENT,+ "a message from an ignored user is not announced"+ );});test("does not announce hidden messages", async function (assert) {@@ -118,7 +129,9 @@ module(await publishSentMessage({ hidden: true });- assert.dom("#a11y-announcements-polite").hasNoText();+ assert+ .dom("#a11y-announcements-polite")+ .hasText(IDLE_ANNOUNCEMENT, "a hidden message is not announced");});test("announces an image-only message as an image", async function (assert) {@@ -192,7 +205,12 @@ module(await publishSentMessage();- assert.dom("#a11y-announcements-polite").hasNoText();+ assert+ .dom("#a11y-announcements-polite")+ .hasText(+ IDLE_ANNOUNCEMENT,+ "nothing is announced once the user has opted out"+ );});test("coalesces a burst of messages into a single summary", async function (assert) {