fix: make ProxyMenu more accessible to screen readers #11312

Parkreiner · 2023-12-21T17:38:40Z

No issue to link – just trying to do some random fixes/improvements since it's the last day before Christmas break. Definitely not expecting anyone to tackle this until after we all get back.

Changes made

Adds a general-purpose Abbr (abbreviation) component that builds on top of the native <abbr> and adds some additional accessibility niceties (plus tests and stories)
Updates the ProxyMenu component to add additional text that provides context for what certain UI elements mean

Parkreiner · 2023-12-21T17:39:16Z

site/src/components/Dashboard/Navbar/NavbarView.tsx

-    return false;
+    //  - The latency reported is older than the refetch date. This means the
+    //    latency is stale and we should show a loading spinner until the new
+    //    latency is fetched.


Only change here is that I reformatted the comment to properly fit in an 80px column

Parkreiner · 2023-12-21T20:07:27Z

site/src/components/Dashboard/Navbar/NavbarView.tsx

@@ -296,6 +308,8 @@ const ProxyMenu: FC<ProxyMenuProps> = ({ proxyContextValue }) => {
          }}
        >
          <h4
+            autoFocus
+            tabIndex={-1}


Safety nets to make extra sure that the header receives focus when the menu opens. 90% sure tabIndex shouldn't be necessary, but it's just a precaution to make sure that it's never directly tab-able as an interactive element

Parkreiner · 2023-12-21T20:08:13Z

site/src/components/Dashboard/Navbar/NavbarView.tsx

@@ -329,6 +349,9 @@ const ProxyMenu: FC<ProxyMenuProps> = ({ proxyContextValue }) => {
          })
          .map((proxy) => (
            <MenuItem
+              key={proxy.id}
+              selected={proxy.id === selectedProxy?.id}
+              css={{ fontSize: 14 }}


Just moving the single-line props to the top to help with readability

Parkreiner · 2023-12-21T20:46:38Z

site/src/components/ProxyStatusLatency/ProxyStatusLatency.tsx

+              color,
+            }}
+          />
+        </>


Annoyingly, Tooltip doesn't accept children arrays, so the Fragment is necessary

Kira-Pilot · 2024-01-02T20:57:48Z

site/src/components/Abbr/Abbr.tsx

+  // issues as the native title attribute as far as screen reader support
+  expandedText: string;
+  children: string;
+  initialism?: boolean;


NIT: what do you think about the var names "tooltipText" (instead of "expandedText") and "hasAcronym" (instead of "initialism")? Expanded makes me think there is a dropdown or accordion and I had to google initialism.

So, I think I've done a bad job of adding enough context:

I can see if there are some better alternatives for expandedText, but with toolTipText, it feels like it's putting much more emphasis on one type of user (sighted users who can see the tooltip), vs accommodating both them and screen-reader users. If a user's been blind all their life, they'll have no idea what a tooltip even is. Even in the WCAG spec, they call this "the expanded form of abbreviations"

The initialism prop is there to make sure that initialisms are pronounced like initialisms instead of just general acronyms/abbreviations. Like, NASA is an acronym, but you wouldn't want to pronounce it like an initialism, because then it'd be read "N-A-S-A"

Ah, thanks for those distinctions; makes sense. I like the proposal you came up with, i.e.
pronunciation?: "shorthand" | "acronym" | "initialism";

Kira-Pilot · 2024-01-02T21:05:51Z

site/src/components/Abbr/Abbr.tsx

+// There isn't a dedicated HTMLAbbrElement type; have to go with base type
+type AbbrProps = Exclude<HTMLAttributes<HTMLElement>, "title" | "children"> & {
+  // Not calling this "title" to make it clear that it doesn't have the same
+  // issues as the native title attribute as far as screen reader support


I don't know that this rename lends a lot of clarity, tbh - I might just use "title" so there's less cognitive overhead

Yeah, I can see that. As I've been doing research, it seems that title is usually next to useless for screen readers, but reframing it like "the API is 99% the same as the native <abbr>, and we fixed the title prop" would make things more clear for other folks

Kira-Pilot · 2024-01-02T21:06:54Z

site/src/components/Abbr/Abbr.test.tsx

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import { Abbr } from "./Abbr";


Kira-Pilot · 2024-01-02T21:08:12Z

site/src/components/Abbr/Abbr.tsx

@@ -0,0 +1,74 @@
+/**


There are a lot of comments in here for a relatively small component. Are there any we can shorten?

Kira-Pilot · 2024-01-02T21:13:33Z

The initializeText fn was a nice touch. It would be good to be on the same page as a team so we can strike the right balance between being accessible and acknowledging the technical expertise of our users. I can see us using this component for an acronym like DERP, but perhaps we shouldn't use it for URL? What are your thoughts?

Parkreiner · 2024-01-03T13:47:53Z

I can see us using this component for an acronym like DERP, but perhaps we shouldn't use it for URL? What are your thoughts?

I think it's kind of up to discretion, but adding it everywhere shouldn't hurt. I think "URL" is established enough that screen readers should pronounce it correctly, but if it ever gets pronounced like "Earl" for whatever reason, this component should be able to help fix that. Then again, that CLI/"klee" example I mentioned in the comments was actually something I ran into for this PR, so it's not really possible to know until it's tested

It would be good to be on the same page as a team so we can strike the right balance between being accessible and acknowledging the technical expertise of our users

Yeah, if Coder were a less specialized, more mass-market product, I'd probably say "slap the component everywhere", just because even if an acronym is obvious to native speakers, it would help people like English-as-a-Second-Language learners. But I feel like even if someone doesn't speak English natively, if they work in software, they probably know these acronyms

Parkreiner · 2024-01-03T14:13:30Z

@Kira-Pilot Ended up taking all the feedback into account, and now I'm realizing that there is a case I didn't properly account for.

It's going to require a bit more manual testing with a screen reader, though, and since this is kind of a "pet project PR", I'm going to put this away until near the end of the week

wip: commit progress on latency update

4e08a23

github-actions bot assigned Parkreiner Dec 21, 2023

Parkreiner commented Dec 21, 2023

View reviewed changes

Parkreiner added 3 commits December 21, 2023 19:57

chore: add stories and clean up tests

1402691

refactor: clean up code

f003144

fix: make sure headers aren't treated as interactive elements

5f58877

Parkreiner requested review from a team and Kira-Pilot and removed request for a team December 21, 2023 20:03

Parkreiner marked this pull request as ready for review December 21, 2023 20:04

Parkreiner commented Dec 21, 2023

View reviewed changes

Parkreiner added 4 commits December 21, 2023 20:12

refactor: clean up tests

1348f55

fix: clean up stories

b7d05de

docs: add clarifying comment

c836057

fix: update stories again

4af5cec

Parkreiner commented Dec 21, 2023

View reviewed changes

Parkreiner added 3 commits December 22, 2023 14:31

fix: clean up/extend prop definitions

9a05ee1

refactor: quick cleanup

cdff5fb

Merge branch 'main' into mes/a11y-proxy-menu

0f3471c

Kira-Pilot reviewed Jan 2, 2024

View reviewed changes

Kira-Pilot approved these changes Jan 2, 2024

View reviewed changes

Parkreiner added 2 commits January 3, 2024 14:15

fix: apply Kira's feedback

fd643ae

refactor: clean up abbr markup to account for pronunciation

8853c5a

Parkreiner added 5 commits January 7, 2024 16:28

fix: more cleanup

3189031

Merge branch 'main' into mes/a11y-proxy-menu

0cfc510

fix: refine screen reader output for VoiceOver

8f38208

refactor: clean up and redefine tests

d534099

feature: add finishing touches

03b2ac1

Parkreiner merged commit 31f8fac into main Jan 7, 2024

Parkreiner deleted the mes/a11y-proxy-menu branch January 7, 2024 23:37

github-actions bot locked and limited conversation to collaborators Jan 7, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

fix: make ProxyMenu more accessible to screen readers #11312

fix: make ProxyMenu more accessible to screen readers #11312

Uh oh!

Parkreiner commented Dec 21, 2023 •

edited

Loading

Uh oh!

Parkreiner Dec 21, 2023

Uh oh!

Parkreiner Dec 21, 2023 •

edited

Loading

Uh oh!

Parkreiner Dec 21, 2023

Uh oh!

Parkreiner Dec 21, 2023 •

edited

Loading

Uh oh!

Kira-Pilot Jan 2, 2024 •

edited

Loading

Uh oh!

Parkreiner Jan 3, 2024

Uh oh!

Kira-Pilot Jan 3, 2024

Uh oh!

Kira-Pilot Jan 2, 2024

Uh oh!

Parkreiner Jan 3, 2024 •

edited

Loading

Uh oh!

Kira-Pilot Jan 2, 2024

Uh oh!

Kira-Pilot Jan 2, 2024

Uh oh!

Kira-Pilot commented Jan 2, 2024

Uh oh!

Parkreiner commented Jan 3, 2024 •

edited

Loading

Uh oh!

Parkreiner commented Jan 3, 2024

Uh oh!

Uh oh!

		@@ -0,0 +1,89 @@
		import { render, screen } from "@testing-library/react";
		import { Abbr } from "./Abbr";

fix: make ProxyMenu more accessible to screen readers #11312

fix: make ProxyMenu more accessible to screen readers #11312

Uh oh!

Conversation

Parkreiner commented Dec 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes made

Uh oh!

Parkreiner Dec 21, 2023

Choose a reason for hiding this comment

Uh oh!

Parkreiner Dec 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Parkreiner Dec 21, 2023

Choose a reason for hiding this comment

Uh oh!

Parkreiner Dec 21, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kira-Pilot Jan 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Parkreiner Jan 3, 2024

Choose a reason for hiding this comment

Uh oh!

Kira-Pilot Jan 3, 2024

Choose a reason for hiding this comment

Uh oh!

Kira-Pilot Jan 2, 2024

Choose a reason for hiding this comment

Uh oh!

Parkreiner Jan 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Kira-Pilot Jan 2, 2024

Choose a reason for hiding this comment

Uh oh!

Kira-Pilot Jan 2, 2024

Choose a reason for hiding this comment

Uh oh!

Kira-Pilot commented Jan 2, 2024

Uh oh!

Parkreiner commented Jan 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Parkreiner commented Jan 3, 2024

Uh oh!

Uh oh!

Parkreiner commented Dec 21, 2023 •

edited

Loading

Parkreiner Dec 21, 2023 •

edited

Loading

Parkreiner Dec 21, 2023 •

edited

Loading

Kira-Pilot Jan 2, 2024 •

edited

Loading

Parkreiner Jan 3, 2024 •

edited

Loading

Parkreiner commented Jan 3, 2024 •

edited

Loading