Skip to content

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.gjs
index 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>
<div
id="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>
<div
id="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.js
index 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.gjs
index 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.gjs
index 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) {