From de0ce6159c3d4920a56393dc387f58c92886b8af Mon Sep 17 00:00:00 2001
From: Eric Sizer <eric.sizer@gmail.com>
Date: Thu, 9 Jan 2025 14:11:28 -0500
Subject: [PATCH 1/5] add aria-sort to table headings

---
 .../src/components/Table/ResponsiveTable/Table.tsx    | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/apps/web/src/components/Table/ResponsiveTable/Table.tsx b/apps/web/src/components/Table/ResponsiveTable/Table.tsx
index ccb623f1f3f..ad5ffd0965c 100644
--- a/apps/web/src/components/Table/ResponsiveTable/Table.tsx
+++ b/apps/web/src/components/Table/ResponsiveTable/Table.tsx
@@ -110,6 +110,8 @@ const Row = (props: RowProps) => (
   />
 );
 
+type AriaSort = "ascending" | "descending" | "none" | undefined;
+
 type CellHTMLProps = DetailedHTMLProps<
   HTMLAttributes<HTMLTableCellElement>,
   HTMLTableCellElement
@@ -123,6 +125,12 @@ const HeadCell = <T,>({ header, ...rest }: HeadCellProps<T>) => {
   const isRowSelect = header.column.columnDef.meta?.isRowSelect;
   const shouldShrink = header.column.columnDef.meta?.shrink;
   const sortingLocked = header.column.columnDef.meta?.sortingLocked;
+  const sortDirection = header.column.getIsSorted();
+  let ariaSort: AriaSort = "none";
+  if (sortDirection) {
+    ariaSort = sortDirection === "asc" ? "ascending" : "descending";
+  }
+
   return (
     <th
       role="columnheader"
@@ -132,6 +140,9 @@ const HeadCell = <T,>({ header, ...rest }: HeadCellProps<T>) => {
       data-h2-font-size="base(caption)"
       data-h2-vertical-align="base(middle)"
       data-h2-font-weight="base(400)"
+      {...(header.column.getCanSort() && {
+        "aria-sort": ariaSort,
+      })}
       {...(!isRowSelect &&
         !shouldShrink && {
           "data-h2-min-width": "base(x8)",

From 2372f18ab3fd7e712f83f05df2341677af1777bb Mon Sep 17 00:00:00 2001
From: Eric Sizer <eric.sizer@gmail.com>
Date: Fri, 10 Jan 2025 08:29:24 -0500
Subject: [PATCH 2/5] improve sort with hints

---
 .../Table/ResponsiveTable/ResponsiveTable.tsx     | 15 ++++++++++++++-
 .../Table/ResponsiveTable/SortButton.tsx          | 14 ++++++++++++--
 .../components/Table/ResponsiveTable/Table.tsx    |  7 ++++---
 3 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx b/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx
index 432ae27a183..bf998aaed45 100644
--- a/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx
+++ b/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx
@@ -320,6 +320,10 @@ const ResponsiveTable = <TData extends object, TFilters = object>({
     };
   }
 
+  const canSort = table
+    .getFlatHeaders()
+    .some((header) => header.column.getCanSort());
+
   return (
     <>
       <Table.Controls add={add}>
@@ -353,7 +357,7 @@ const ResponsiveTable = <TData extends object, TFilters = object>({
                 {table.getHeaderGroups().map((headerGroup) => (
                   <Table.HeadRow key={headerGroup.id}>
                     {headerGroup.headers.map((header) => (
-                      <Table.HeadCell key={header.id} header={header} />
+                      <Table.HeadCell key={header.id} id={id} header={header} />
                     ))}
                   </Table.HeadRow>
                 ))}
@@ -397,6 +401,15 @@ const ResponsiveTable = <TData extends object, TFilters = object>({
           )}
         </>
       )}
+      {canSort && (
+        <span id={`sortHint-${id}`} data-h2-display="base(none)">
+          {intl.formatMessage({
+            defaultMessage: "Sort",
+            id: "LwruRb",
+            description: "Hint to let users know a table column can be sorted",
+          })}
+        </span>
+      )}
     </>
   );
 };
diff --git a/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx b/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx
index 40afcc3ab66..6fe25b525e7 100644
--- a/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx
+++ b/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx
@@ -4,7 +4,7 @@ import ArrowDownIcon from "@heroicons/react/20/solid/ArrowDownIcon";
 import ArrowUpIcon from "@heroicons/react/20/solid/ArrowUpIcon";
 import ArrowsUpDownIcon from "@heroicons/react/20/solid/ArrowsUpDownIcon";
 import LockClosedIcon from "@heroicons/react/24/solid/LockClosedIcon";
-import { ReactNode } from "react";
+import { ReactNode, useId } from "react";
 
 import { Button } from "@gc-digital-talent/ui";
 
@@ -12,10 +12,18 @@ interface SortButtonProps<T> {
   column: Column<T, unknown>;
   children: ReactNode;
   locked?: boolean;
+  tableId: string;
 }
 
-const SortButton = <T,>({ column, locked, children }: SortButtonProps<T>) => {
+const SortButton = <T,>({
+  column,
+  locked,
+  tableId,
+  children,
+}: SortButtonProps<T>) => {
   const intl = useIntl();
+  const id = useId();
+  const ariaId = `${column.id}-${id}`;
 
   if (!column.getCanSort()) {
     // eslint-disable-next-line react/jsx-no-useless-fragment
@@ -30,6 +38,8 @@ const SortButton = <T,>({ column, locked, children }: SortButtonProps<T>) => {
 
   return (
     <Button
+      id={ariaId}
+      aria-labelledby={`${ariaId} sortHint-${tableId}`}
       mode="inline"
       color="whiteFixed"
       fontSize="caption"
diff --git a/apps/web/src/components/Table/ResponsiveTable/Table.tsx b/apps/web/src/components/Table/ResponsiveTable/Table.tsx
index ad5ffd0965c..994f0f9cf7e 100644
--- a/apps/web/src/components/Table/ResponsiveTable/Table.tsx
+++ b/apps/web/src/components/Table/ResponsiveTable/Table.tsx
@@ -119,14 +119,15 @@ type CellHTMLProps = DetailedHTMLProps<
 
 type HeadCellProps<T> = {
   header: Header<T, unknown>;
+  id: string;
 } & CellHTMLProps;
 
-const HeadCell = <T,>({ header, ...rest }: HeadCellProps<T>) => {
+const HeadCell = <T,>({ header, id, ...rest }: HeadCellProps<T>) => {
   const isRowSelect = header.column.columnDef.meta?.isRowSelect;
   const shouldShrink = header.column.columnDef.meta?.shrink;
   const sortingLocked = header.column.columnDef.meta?.sortingLocked;
   const sortDirection = header.column.getIsSorted();
-  let ariaSort: AriaSort = "none";
+  let ariaSort: AriaSort = undefined;
   if (sortDirection) {
     ariaSort = sortDirection === "asc" ? "ascending" : "descending";
   }
@@ -151,7 +152,7 @@ const HeadCell = <T,>({ header, ...rest }: HeadCellProps<T>) => {
       {...rest}
     >
       {header.isPlaceholder ? null : (
-        <SortButton column={header.column} locked={sortingLocked}>
+        <SortButton tableId={id} column={header.column} locked={sortingLocked}>
           {flexRender(header.column.columnDef.header, header.getContext())}
         </SortButton>
       )}

From 41142c95f392ad0a9b4f7e888e6716d9e98c14d3 Mon Sep 17 00:00:00 2001
From: Eric Sizer <eric.sizer@gmail.com>
Date: Fri, 10 Jan 2025 08:33:13 -0500
Subject: [PATCH 3/5] remove parentheses

---
 .../Table/ResponsiveTable/SortButton.tsx         |  8 ++++----
 apps/web/src/lang/fr.json                        | 16 ++++++++--------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx b/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx
index 6fe25b525e7..d2b9999de7b 100644
--- a/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx
+++ b/apps/web/src/components/Table/ResponsiveTable/SortButton.tsx
@@ -58,14 +58,14 @@ const SortButton = <T,>({
         <span data-h2-visually-hidden="base(invisible)">
           {sortDirection === "asc"
             ? intl.formatMessage({
-                defaultMessage: " (Ascending)",
-                id: "90E1fF",
+                defaultMessage: "Ascending",
+                id: "RGHXLW",
                 description:
                   "Message added to indicate a table column is sorted in ascending order",
               })
             : intl.formatMessage({
-                defaultMessage: " (Descending)",
-                id: "uKD+km",
+                defaultMessage: "Descending",
+                id: "zIv0jm",
                 description:
                   "Message added to indicate a table column is sorted in descending order",
               })}
diff --git a/apps/web/src/lang/fr.json b/apps/web/src/lang/fr.json
index 964d42f373b..e8f79d53d06 100644
--- a/apps/web/src/lang/fr.json
+++ b/apps/web/src/lang/fr.json
@@ -2147,10 +2147,6 @@
     "defaultMessage": "Conditions favorables",
     "description": "Heading for the directives digital enabling conditions component"
   },
-  "90E1fF": {
-    "defaultMessage": "(Ordre croissant)",
-    "description": "Message added to indicate a table column is sorted in ascending order"
-  },
   "91b+W0": {
     "defaultMessage": "Niveau exigé",
     "description": "Required skill level column header for tables"
@@ -5775,6 +5771,10 @@
     "defaultMessage": "Date d’attribution",
     "description": "Label displayed on award form for date awarded input"
   },
+  "RGHXLW": {
+    "defaultMessage": "Ordre croissant",
+    "description": "Message added to indicate a table column is sorted in ascending order"
+  },
   "RGl+Dr": {
     "defaultMessage": "Cette possibilité d'emploi s'adresse aux employés internes",
     "description": "Title of a note describing that a pool is only open to employees"
@@ -11474,10 +11474,6 @@
     "defaultMessage": "Le contrat comporte-t-il des exigences particulières en matière de personnel?",
     "description": "Label for _contract amendable_ fieldset in the _digital services contracting questionnaire_"
   },
-  "uKD+km": {
-    "defaultMessage": "(Ordre décroissant)",
-    "description": "Message added to indicate a table column is sorted in descending order"
-  },
   "uLncuU": {
     "defaultMessage": "Nom du (de la) candidat(e)",
     "description": "Title displayed on the User table Candidate name column."
@@ -12342,6 +12338,10 @@
     "defaultMessage": "Veuillez répondre à ces questions au mieux de vos capacités afin d'aider les gestionnaires d'embauche à mieux comprendre pourquoi vous correspondez à l'occasion d'emploi.",
     "description": "Reminder what general questions are used for."
   },
+  "zIv0jm": {
+    "defaultMessage": "Ordre décroissant",
+    "description": "Message added to indicate a table column is sorted in descending order"
+  },
   "zJKngJ": {
     "defaultMessage": "Gérer votre expérience et les processus de recrutement pour lesquels vous êtes qualifié(e).",
     "description": "Description for the Career timeline and recruitment page in applicant profile."

From 38fbe04661f3f10ee241aa1b509a896e4a9ca407 Mon Sep 17 00:00:00 2001
From: Eric Sizer <eric.sizer@gmail.com>
Date: Fri, 10 Jan 2025 09:31:51 -0500
Subject: [PATCH 4/5] add translation

---
 apps/web/src/lang/fr.json | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/apps/web/src/lang/fr.json b/apps/web/src/lang/fr.json
index e8f79d53d06..8587ddf5214 100644
--- a/apps/web/src/lang/fr.json
+++ b/apps/web/src/lang/fr.json
@@ -4707,6 +4707,10 @@
     "defaultMessage": "Expérience minimale ou combinaison équivalente d'études",
     "description": "Title for Minimum experience or equivalent education"
   },
+  "LwruRb": {
+    "defaultMessage": "Trier",
+    "description": "Hint to let users know a table column can be sorted"
+  },
   "LxRoWB": {
     "defaultMessage": "Création de la collectivité réussie!",
     "description": "Message displayed after a community is created"

From 6885895a1de93c216ea700e75fae6907c1c6400d Mon Sep 17 00:00:00 2001
From: Eric Sizer <eric.sizer@gmail.com>
Date: Mon, 13 Jan 2025 15:16:45 -0500
Subject: [PATCH 5/5] add update annoncement back

---
 .../Table/ResponsiveTable/ResponsiveTable.tsx | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx b/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx
index 59cc8526c80..8c7dc6cafe8 100644
--- a/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx
+++ b/apps/web/src/components/Table/ResponsiveTable/ResponsiveTable.tsx
@@ -326,6 +326,34 @@ const ResponsiveTable = <TData extends object, TFilters = object>({
   const canSort = table
     .getFlatHeaders()
     .some((header) => header.column.getCanSort());
+  const totalRows = paginationAdjusted?.total;
+  const debouncedAnnouncement = debounce((count: number) => {
+    announce(
+      intl.formatMessage(
+        {
+          defaultMessage:
+            "{total, plural, =0 {0 results found} =1 {1 result found} other {# results found}}",
+          id: "SLYAoc",
+          description:
+            "Message announced to assistive technology when number of items in a table changes",
+        },
+        { total: count },
+      ),
+    );
+  }, 300);
+
+  useEffect(() => {
+    const hasItems = typeof totalRows !== "undefined" && totalRows !== null;
+    if (hasItems && !hasUpdatedRows.current) {
+      hasUpdatedRows.current = true;
+      return;
+    }
+    if (hasItems && hasUpdatedRows.current) {
+      debouncedAnnouncement(totalRows ?? 0);
+    }
+    // Note, exhaustive-deps causes over announcing
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [totalRows]);
 
   return (
     <>