From 0e3ed7ea2a67b56629cbca12ab428da4b3b2ba6d Mon Sep 17 00:00:00 2001
From: Kris <kris.aubuchon@discourse.org>
Date: Wed, 10 Jul 2024 13:14:36 -0400
Subject: [PATCH] A11Y: improve topic list table markup for screenreaders
 (#27808)

Co-authored-by: Jarek Radosz <jradosz@gmail.com>
---
 .../discourse/app/components/topic-list.hbs   |  2 ++
 .../app/components/topic-list/list.gjs        |  1 +
 .../components/topic-list/topic-entrance.gjs  |  1 +
 .../topic-list/topic-list-header-column.gjs   | 12 ++++++----
 .../topic-list/topic-list-header.gjs          |  7 ++----
 .../raw-templates/list/posts-count-column.hbr |  4 ++--
 .../topic-list-header-column.hbr              |  4 ++--
 .../app/raw-templates/topic-list-header.hbr   | 12 +++++-----
 .../app/raw-views/list/posts-count-column.js  |  5 +++-
 config/locales/client.en.yml                  | 23 ++++++++-----------
 spec/lib/js_locale_helper_spec.rb             |  4 ++--
 11 files changed, 40 insertions(+), 35 deletions(-)

diff --git a/app/assets/javascripts/discourse/app/components/topic-list.hbs b/app/assets/javascripts/discourse/app/components/topic-list.hbs
index 26613c77bdc..9f5f54cdbc1 100644
--- a/app/assets/javascripts/discourse/app/components/topic-list.hbs
+++ b/app/assets/javascripts/discourse/app/components/topic-list.hbs
@@ -1,3 +1,5 @@
+<caption class="sr-only">{{i18n "sr_topic_list_caption"}}</caption>
+
 <thead class="topic-list-header">
   {{raw
     "topic-list-header"
diff --git a/app/assets/javascripts/discourse/app/components/topic-list/list.gjs b/app/assets/javascripts/discourse/app/components/topic-list/list.gjs
index 0e038671966..fe71c3d97c6 100644
--- a/app/assets/javascripts/discourse/app/components/topic-list/list.gjs
+++ b/app/assets/javascripts/discourse/app/components/topic-list/list.gjs
@@ -101,6 +101,7 @@ export default class TopicList extends Component {
         (if this.bulkSelectEnabled "sticky-header")
       }}
     >
+      <caption class="sr-only">{{i18n "sr_topic_list_caption"}}</caption>
       <thead class="topic-list-header">
         <TopicListHeader
           @canBulkSelect={{@canBulkSelect}}
diff --git a/app/assets/javascripts/discourse/app/components/topic-list/topic-entrance.gjs b/app/assets/javascripts/discourse/app/components/topic-list/topic-entrance.gjs
index 19b3a052308..af11aa2fb3f 100644
--- a/app/assets/javascripts/discourse/app/components/topic-list/topic-entrance.gjs
+++ b/app/assets/javascripts/discourse/app/components/topic-list/topic-entrance.gjs
@@ -66,6 +66,7 @@ export default class TopicEntrance extends Component {
 
   <template>
     <DMenu
+      @title={{@title}}
       @ariaLabel={{@title}}
       @placement="center"
       @autofocus={{true}}
diff --git a/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header-column.gjs b/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header-column.gjs
index ec6c45065d1..66838dcee3f 100644
--- a/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header-column.gjs
+++ b/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header-column.gjs
@@ -83,9 +83,6 @@ export default class TopicListHeaderColumn extends Component {
       {{(if @sortable (modifier on "keydown" this.onKeyDown))}}
       data-sort-order={{@order}}
       scope="col"
-      tabindex={{if @sortable "0"}}
-      role={{if @sortable "button"}}
-      aria-pressed={{this.isSorting}}
       aria-sort={{this.ariaSort}}
       class={{concatClass
         "topic-list-data"
@@ -144,7 +141,14 @@ export default class TopicListHeaderColumn extends Component {
             @changeNewListSubset={{@changeNewListSubset}}
           />
         {{else}}
-          <span>{{this.localizedName}}</span>
+          <span
+            class={{if @screenreaderOnly "sr-only"}}
+            tabindex={{if @sortable "0"}}
+            role={{if @sortable "button"}}
+            aria-pressed={{this.isSorting}}
+          >
+            {{this.localizedName}}
+          </span>
         {{/if}}
       {{/unless}}
 
diff --git a/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header.gjs b/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header.gjs
index eaafa282e48..e33cce7ef2e 100644
--- a/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header.gjs
+++ b/app/assets/javascripts/discourse/app/components/topic-list/topic-list-header.gjs
@@ -50,6 +50,8 @@ const TopicListHeader = <template>
         @activeOrder={{@order}}
         @changeSort={{@changeSort}}
         @ascending={{@ascending}}
+        @name="posters"
+        @screenreaderOnly={{true}}
         aria-label={{i18n "category.sort_options.posters"}}
       />
     {{/if}}
@@ -62,7 +64,6 @@ const TopicListHeader = <template>
       @changeSort={{@changeSort}}
       @ascending={{@ascending}}
       @name="replies"
-      aria-label={{i18n "sr_replies"}}
     />
 
     {{#if @showLikes}}
@@ -74,7 +75,6 @@ const TopicListHeader = <template>
         @changeSort={{@changeSort}}
         @ascending={{@ascending}}
         @name="likes"
-        aria-label={{i18n "sr_likes"}}
       />
     {{/if}}
 
@@ -87,7 +87,6 @@ const TopicListHeader = <template>
         @changeSort={{@changeSort}}
         @ascending={{@ascending}}
         @name="likes"
-        aria-label={{i18n "sr_op_likes"}}
       />
     {{/if}}
 
@@ -99,7 +98,6 @@ const TopicListHeader = <template>
       @changeSort={{@changeSort}}
       @ascending={{@ascending}}
       @name="views"
-      aria-label={{i18n "sr_views"}}
     />
 
     <TopicListHeaderColumn
@@ -110,7 +108,6 @@ const TopicListHeader = <template>
       @changeSort={{@changeSort}}
       @ascending={{@ascending}}
       @name="activity"
-      aria-label={{i18n "sr_activity"}}
     />
 
     <PluginOutlet @name="topic-list-header-after" />
diff --git a/app/assets/javascripts/discourse/app/raw-templates/list/posts-count-column.hbr b/app/assets/javascripts/discourse/app/raw-templates/list/posts-count-column.hbr
index f4836f416e3..71d40199e97 100644
--- a/app/assets/javascripts/discourse/app/raw-templates/list/posts-count-column.hbr
+++ b/app/assets/javascripts/discourse/app/raw-templates/list/posts-count-column.hbr
@@ -1,5 +1,5 @@
-<{{view.tagName}} class='num posts-map posts {{view.likesHeat}} topic-list-data' title='{{view.title}}'>
-  <button class="btn-link posts-map badge-posts {{view.likesHeat}}" aria-label="{{view.title}}">
+<{{view.tagName}} class='num posts-map posts {{view.likesHeat}} topic-list-data'>
+  <button class="btn-link posts-map badge-posts {{view.likesHeat}}" title="{{view.title}}" aria-label="{{view.title}}">
     {{raw-plugin-outlet name="topic-list-before-reply-count"}}
     {{number topic.replyCount noTitle="true"}}
   </button>
diff --git a/app/assets/javascripts/discourse/app/raw-templates/topic-list-header-column.hbr b/app/assets/javascripts/discourse/app/raw-templates/topic-list-header-column.hbr
index 729a9f0c4b1..881a4381f2c 100644
--- a/app/assets/javascripts/discourse/app/raw-templates/topic-list-header-column.hbr
+++ b/app/assets/javascripts/discourse/app/raw-templates/topic-list-header-column.hbr
@@ -1,4 +1,4 @@
-<th data-sort-order='{{order}}' class='{{view.className}} topic-list-data' scope="col" {{#if ariaLabel}}aria-label='{{ariaLabel}}'{{/if}} {{#if sortable}}tabindex="0" role="button" aria-pressed='{{view.ariaPressed}}' {{#if view.ariaSort}}aria-sort='{{view.ariaSort}}'{{/if}} {{/if}}>
+<th data-sort-order='{{order}}' class='{{view.className}} topic-list-data' scope="col" {{#if view.ariaSort}}aria-sort='{{view.ariaSort}}'{{/if}}>
   {{~#if canBulkSelect}}
     {{~#if showBulkToggle}}
       {{~#if experimentalTopicBulkActionsEnabled }}
@@ -25,7 +25,7 @@
     {{~#if view.showTopicsAndRepliesToggle}}
       {{raw "list/new-list-header-controls" current=newListSubset newRepliesCount=newRepliesCount newTopicsCount=newTopicsCount}}
     {{else}}
-      <span>{{view.localizedName}}</span>
+      <span {{#if view.screenreaderOnly}}class="sr-only"{{/if}} {{#if sortable}}tabindex="0" role="button" aria-pressed='{{view.ariaPressed}}'{{/if}}>{{view.localizedName}}</span>
     {{/if ~}}
   {{/unless ~}}
   {{~#if view.isSorting}}
diff --git a/app/assets/javascripts/discourse/app/raw-templates/topic-list-header.hbr b/app/assets/javascripts/discourse/app/raw-templates/topic-list-header.hbr
index cd65576495a..924b8301557 100644
--- a/app/assets/javascripts/discourse/app/raw-templates/topic-list-header.hbr
+++ b/app/assets/javascripts/discourse/app/raw-templates/topic-list-header.hbr
@@ -13,15 +13,15 @@
 {{raw "topic-list-header-column" order='default' name=listTitle bulkSelectEnabled=bulkSelectEnabled showBulkToggle=toggleInTitle canBulkSelect=canBulkSelect canDoBulkActions=canDoBulkActions showTopicsAndRepliesToggle=showTopicsAndRepliesToggle newListSubset=newListSubset newRepliesCount=newRepliesCount newTopicsCount=newTopicsCount experimentalTopicBulkActionsEnabled=experimentalTopicBulkActionsEnabled bulkSelectHelper=bulkSelectHelper }}
 {{raw-plugin-outlet name="topic-list-header-after-main-link"}}
 {{#if showPosters}}
-  {{raw "topic-list-header-column" order='posters' ariaLabel=(i18n "category.sort_options.posters")}}
+  {{raw "topic-list-header-column" name='posters' screenreaderOnly='true'}}
 {{/if}}
-{{raw "topic-list-header-column" sortable=sortable number='true' order='posts' name='replies' ariaLabel=(i18n "sr_replies")}}
+{{raw "topic-list-header-column" sortable=sortable number='true' order='posts' name='replies'}}
 {{#if showLikes}}
-  {{raw "topic-list-header-column" sortable=sortable number='true' order='likes' name='likes' ariaLabel=(i18n "sr_likes")}}
+  {{raw "topic-list-header-column" sortable=sortable number='true' order='likes' name='likes'}}
 {{/if}}
 {{#if showOpLikes}}
-  {{raw "topic-list-header-column" sortable=sortable number='true' order='op_likes' name='likes' ariaLabel=(i18n "sr_op_likes")}}
+  {{raw "topic-list-header-column" sortable=sortable number='true' order='op_likes' name='likes'}}
 {{/if}}
-{{raw "topic-list-header-column" sortable=sortable number='true' order='views' name='views' ariaLabel=(i18n "sr_views")}}
-{{raw "topic-list-header-column" sortable=sortable number='true' order='activity' name='activity' ariaLabel=(i18n "sr_activity")}}
+{{raw "topic-list-header-column" sortable=sortable number='true' order='views' name='views'}}
+{{raw "topic-list-header-column" sortable=sortable number='true' order='activity' name='activity'}}
 {{~raw-plugin-outlet name="topic-list-header-after"~}}
diff --git a/app/assets/javascripts/discourse/app/raw-views/list/posts-count-column.js b/app/assets/javascripts/discourse/app/raw-views/list/posts-count-column.js
index 86ff4208090..2699fda62b7 100644
--- a/app/assets/javascripts/discourse/app/raw-views/list/posts-count-column.js
+++ b/app/assets/javascripts/discourse/app/raw-views/list/posts-count-column.js
@@ -19,7 +19,10 @@ export default EmberObject.extend({
 
   @discourseComputed("topic.replyCount", "ratioText")
   title(count, ratio) {
-    return I18n.messageFormat("posts_likes_MF", { count, ratio }).trim();
+    return I18n.messageFormat("posts_likes_MF", {
+      count,
+      ratio,
+    });
   },
 
   @discourseComputed("ratio")
diff --git a/config/locales/client.en.yml b/config/locales/client.en.yml
index 2ab2eb0f928..dac5a61d1e2 100644
--- a/config/locales/client.en.yml
+++ b/config/locales/client.en.yml
@@ -4141,36 +4141,33 @@ en:
     pending_posts:
       label: "Pending"
       label_with_count: "Pending (%{count})"
+    sr_topic_list_caption: Topic list, column headers with buttons are sortable.
 
     # This string uses the ICU Message Format. See https://meta.discourse.org/t/7035 for translation guidelines.
     posts_likes_MF: |
-      This topic has { count, plural,
-          one {# reply}
-        other {# replies}
-      } { ratio, select,
-          low {with a high like to post ratio}
-          med {with a very high like to post ratio}
-         high {with an extremely high like to post ratio}
+      { count, plural,
+          one {# reply,}
+        other {# replies,}
+      }{ ratio, select,
+          low { high like to post ratio,}
+          med { very high like to post ratio,}
+         high { extremely high like to post ratio,}
         other {}
-      }
+      } jump to the first or last post…
 
+    posters: "Posters"
     latest_poster_link: "%{username}'s profile, latest poster"
     original_post: "Original Post"
     views: "Views"
-    sr_views: "Sort by views"
     views_lowercase:
       one: "view"
       other: "views"
     replies: "Replies"
-    sr_replies: "Sort by replies"
     views_long:
       one: "this topic has been viewed %{count} time"
       other: "this topic has been viewed %{count} times"
     activity: "Activity"
-    sr_activity: "Sort by activity"
     likes: "Likes"
-    sr_likes: "Sort by likes"
-    sr_op_likes: "Sort by original post likes"
     likes_lowercase:
       one: "like"
       other: "likes"
diff --git a/spec/lib/js_locale_helper_spec.rb b/spec/lib/js_locale_helper_spec.rb
index 24bf9ec746a..4e989a28ec6 100644
--- a/spec/lib/js_locale_helper_spec.rb
+++ b/spec/lib/js_locale_helper_spec.rb
@@ -172,7 +172,7 @@ RSpec.describe JsLocaleHelper do
       it "translates messages properly" do
         expect(
           translated_message,
-        ).to eq "This topic has 3 replies with a very high like to post ratio\n"
+        ).to eq "3 replies, very high like to post ratio, jump to the first or last post…\n"
       end
 
       context "when the translation is overriden" do
@@ -207,7 +207,7 @@ RSpec.describe JsLocaleHelper do
         it "returns the fallback translation" do
           expect(
             translated_message,
-          ).to eq "This topic has 3 replies with a very high like to post ratio\n"
+          ).to eq "3 replies, very high like to post ratio, jump to the first or last post…\n"
         end
 
         context "when the fallback translation is overriden" do