[EuiCodeBlock] Improve accessibility of expandable code blocks #8195

mgadewoll · 2024-11-28T16:15:58Z

Summary

closes #8175.

This PR aims to improve the accessibility of the EuiCodeBlock component, especially the expandable/fullscreen functionality.

Accessibility issues

focusable code blocks did not have any semantic information (the code block is focusable when a height is set to provide scrolling via arrow keys - similar to a listbox pattern)
entering fullscreen mode (expanded code block) did not announce the change to screen reader users
closing the fullscreen mode via the collapse button did not return the focus to the toggle button

Changes

focusable code blocks did not have any semantic information

<pre> elements don't have any semantic information (without adding a specific role) and hence also don't support aria-label to add additional semantic information directly. <code> elements don't accept aria-label and similar attributes either.

To address this a screen-reader only text was added inside the element to be read with the content. This includes the language prop of the code block to increase context.

// example for language="html"

html code block:
<p>
  <!-- Hello world -->
</p>

entering fullscreen mode (expanded code block) did not announce the change to screen reader users

The fullscreen wrapper was not semantically marked and therefore did not provide any information about context change. The container is fullscreen and it has a focus trap, therefore it should be semantically defined as a dialog. Additionally this allows to apply an aria-label to the element, providing context on opening the dialog.

This will result in the following experience:

user opens dialog (expands code block)

screen reader output: "Expanded code bock, dialog"
depending on setting the screen reader might read the content of the dialog

the code block is focused

screen reader reads: html code block: <p> ...

ArrowUp/Down keys navigate the code block content line by line (screen reader browse modes)
Escape key anywhere in the dialog closes the dialog and returns the focus to the expand button
clicking the collapse button or pressing Enter key on it closes the dialog and returns the focus to the expand button

closing the fullscreen mode via the collapse button did not return the focus to the toggle button

This PR adds a small change to the toggle functionality to ensure the focus is returned to the expand button when closing the fullscreen dialog.

Testing

NVDA

Screen.Recording.2024-11-28.at.15.37.22.mov

JAWS

Screen.Recording.2024-11-28.at.15.35.41.mov

QA

open the EuiCodeBlock story and set the overflowHeight control to 50 to reduce the height and enable the expandable code block

#generic

verify the code block can be navigated entirely by keyboard
verify there is no regression (Storybook, EUI docs) in functionality with production (Storybook, EUI docs)
verify that copying the code of a code block does not include the screen reader only label

#a11y

verify the component provides sufficient semantic context and focus management
- verify the code block screen-reader only label is read, announcing it as code block of a specific type (depending on language prop)
- verify the fullscreen element is a dialog and aria-label is read on opening (reading "Expanded code block, dialog")
- verify dialog content can be navigated and closed with screen reader navigation and default keyboard navigation

General checklist

Browser QA
- ~~Checked in both light and dark modes~~
- Checked in mobile
- Checked in Chrome, Safari, Edge, and Firefox
- Checked for accessibility including keyboard-only and screenreader modes
Docs site QA
- Added documentation
- ~~Props have proper autodocs (using @default if default values are missing) and **[playground toggles]~~(https://github.com/elastic/eui/blob/main/wiki/contributing-to-eui/documenting/playgrounds.md)**
- ~~Checked Code Sandbox works for any docs examples~~
Code quality checklist
- Added or updated jest and cypress tests
- Updated visual regression tests
Release checklist
- A changelog entry exists and is marked appropriately.
- ~~If applicable, added the breaking change issue label (and filled out the breaking change checklist)~~
Designer checklist
- If applicable, file an issue to update EUI's Figma library with any corresponding UI changes. (This is an internal repo, if you are external to Elastic, ask a maintainer to submit this request)

weronikaolejniczak

The changes look clean and the result is as expected, yay! 🥳 The code block is announced correctly both on focus and expansion.

I tried EuiCodeBlock with and without overflowHeight and isCopyable set.

2 questions:

Do you think it would be sensible to cover this by an automated a11y test?
Do we want this first approved by an accessibility contractor? Maybe it would be useful to make it a part of all (/most) accessibility tickets and have this check in the PR template?

Role and label:

VoiceOver:

no overflowHeight set:

Screen.Recording.2024-11-29.at.15.10.26.mov

overflowHeight set to 1:

Screen.Recording.2024-11-29.at.15.11.01.mov

overflowHeight set to 1 and isCopyable to true:

Screen.Recording.2024-11-29.at.15.13.13.mov

Note: IMO the UX for copying the content could be improved. There's no information that the content has been copied on clicking the button.

I have 2 more suggestions and a question below 👇🏻

packages/eui/changelogs/upcoming/8195.md

packages/eui/src/components/code/code_block_full_screen.tsx

weronikaolejniczak · 2024-11-29T13:47:11Z

packages/eui/src/components/code/code_block_full_screen.tsx

+    return showFullScreenButton ? (
+      isFullScreen ? (
+        // use delay to prevent label being updated in non-fullscreen state before fullscreen is opened
+        // otherwise this causes screen readers to read the collapse label before anything else (as the button was focused when opening)


non-blocking question: By "read (...) before anything else" we mean before the information that a dialog has opened?

Yes, because how its build currently it uses the same button outside and inside the fullscreen dialog.
It seemed while the "Expand" button is focused and then opened and updated based on the isFullscreen condition it's already read out before the dialog had properly opened and applied focus to read the intended content instead.

weronikaolejniczak · 2024-11-29T13:56:56Z

packages/eui/src/components/code/code_block.tsx

+  );
+  // pre tags don't accept aria-label without an
+  // appropriate role, we add a SR only text instead
+  const codeBlockLabelElement = (


praise: That's a clever workaround 👍🏻 it does generate some code because we need to strip the screen-reader-only content before copying but it's clean.

Fyi, I'm reusing the screen-reader-only copy mechanics introduced in this PR

mgadewoll · 2024-11-29T14:46:37Z

@L1nBra Could you have a look as well (ref original issue)?

mgadewoll · 2024-11-29T14:57:15Z

@weronikaolejniczak

Do you think it would be sensible to cover this by an automated a11y test?

We could add a general test to cover keyboard navigation, yes. Beyond that we couldn't test much further as we can't assert screen reader output. (unless we implement something like guidepup)

Do we want this first approved by an accessibility contractor? Maybe it would be useful to make it a part of all (/most) accessibility tickets and have this check in the PR template?

Thanks for the reminder, I wanted to ping the contractor yesterday but forgot 😅

I'm not sure this needs to be a standard per se. 🤔 If we add it we should make it a) optional (default) and b) non-blocker.
I do think it's sensible to add the contractor if they raised the issue or if we have additional questions. But I think they might already have a lot on their plates and might not always be very responsive which could create bottlenecks. The baseline we can handle within the team I think.
But I'm open for opinions 🙂

mgadewoll · 2024-11-29T15:03:02Z

@weronikaolejniczak Thanks for checking in VoiceOver! That's great to have an additional check. Just fyi, we need to keep in mind that VoiceOver is not the screen reader used by the majority of screen reader users. (there is no statistics but the regular Webaim screen reader surveys give us some idea)
Therefore we should always ensure to verify NVDA and/or JAWS on Windows mainly, while VoiceOver can be an additional check (that also means we optimize for Windows screen readers if the experience diverges) 🙂

kibanamachine · 2024-11-29T16:48:31Z

Preview staging links for this PR:

Docs site: https://eui.elastic.co/pr_8195/
Storybook: https://eui.elastic.co/pr_8195/storybook
New docs: https://eui.elastic.co/pr_8195/new-docs

elasticmachine · 2024-11-29T16:49:00Z

💔 Build Failed

Buildkite Build
Commit: 8843ba7

Failed CI Steps

🔨 EUI pull request test

History

💚 Build #3159 succeeded ca96882
💔 Build #3158 failed b0b0ae6

mgadewoll added 3 commits November 28, 2024 16:56

refactor: improves expanded code block accessibility

d1c2c19

chore: add changelog

b0b0ae6

refactor: ensure screen reader text is not included in copied code

ca96882

mgadewoll marked this pull request as ready for review November 28, 2024 18:55

mgadewoll requested a review from a team as a code owner November 28, 2024 18:55

weronikaolejniczak reviewed Nov 29, 2024

View reviewed changes

mgadewoll added 2 commits November 29, 2024 17:20

test: add keyboard navigation unit test

b8b730d

chore: cleanup

8843ba7

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[EuiCodeBlock] Improve accessibility of expandable code blocks #8195

[EuiCodeBlock] Improve accessibility of expandable code blocks #8195

mgadewoll commented Nov 28, 2024 •

edited

Loading

weronikaolejniczak left a comment •

edited

Loading

weronikaolejniczak Nov 29, 2024 •

edited

Loading

mgadewoll Nov 29, 2024 •

edited

Loading

weronikaolejniczak Nov 29, 2024 •

edited

Loading

mgadewoll Nov 29, 2024

mgadewoll commented Nov 29, 2024

mgadewoll commented Nov 29, 2024 •

edited

Loading

mgadewoll commented Nov 29, 2024

kibanamachine commented Nov 29, 2024

elasticmachine commented Nov 29, 2024

[EuiCodeBlock] Improve accessibility of expandable code blocks #8195

Are you sure you want to change the base?

[EuiCodeBlock] Improve accessibility of expandable code blocks #8195

Conversation

mgadewoll commented Nov 28, 2024 • edited Loading

Summary

Accessibility issues

Changes

Testing

QA

General checklist

weronikaolejniczak left a comment • edited Loading

Choose a reason for hiding this comment

Role and label:

VoiceOver:

weronikaolejniczak Nov 29, 2024 • edited Loading

Choose a reason for hiding this comment

mgadewoll Nov 29, 2024 • edited Loading

Choose a reason for hiding this comment

weronikaolejniczak Nov 29, 2024 • edited Loading

Choose a reason for hiding this comment

mgadewoll Nov 29, 2024

Choose a reason for hiding this comment

mgadewoll commented Nov 29, 2024

mgadewoll commented Nov 29, 2024 • edited Loading

mgadewoll commented Nov 29, 2024

kibanamachine commented Nov 29, 2024

elasticmachine commented Nov 29, 2024

💔 Build Failed

Failed CI Steps

History

mgadewoll commented Nov 28, 2024 •

edited

Loading

weronikaolejniczak left a comment •

edited

Loading

weronikaolejniczak Nov 29, 2024 •

edited

Loading

mgadewoll Nov 29, 2024 •

edited

Loading

weronikaolejniczak Nov 29, 2024 •

edited

Loading

mgadewoll commented Nov 29, 2024 •

edited

Loading