USWDS - File input: Fix issues with voice command #5213

amyleadem · 2023-04-03T17:39:41Z

Summary

Improved the file input experience for voice command and screen reader users. Voice command users can now more easily interact with the component by speaking the visible instructions text. Additionally, screen reader users now have access to both the visible instructions text (in the aria-label) and the file selection status (in a newly created screen reader-only element).

Breaking change

This is not a breaking change.
All changes have been handled dynamically.

Related issue

Closes #5192

As a future enhancement, issue #5238 will create data attributes that will allow users to customize the status and instructions text.

Related pull requests

Changelog update: uswds/uswds-site#2088

Preview link

Preview link: File input

Problem statement

Users of assistive technologies should be able to intuitively access all form elements, understand what action they should take, and receive feedback so that they can confirm that the information they have added is correct. However, the file input component presents problems for both screen reader and voice command users:

Voice command issues

Because of file input's structure, voice command does not work in an intuitive way. A user would expect to vocalize the text shown on screen as part of a "Click" command. For file input, this would mean the user would expect to say something like "Click drag file here or choose from folder" or ""Click choose from folder" to interact with the file input. However, neither of these work because the accessibility tree does not include this information.

Screen readers issues

Screen reader users do not have access to the instructions text ("Drag file here or choose from folder"). Instead, the aria-label provides feedback on the file selection status. This is insufficient information for interaction. The default aria-label "no file selected" does not clearly communicate what the input is or what the user should do, which can lead to confusion.

Solution

To allow voice command users to easily access the file input component, we should make sure the input aria-label matches the visible text as the status changes.

To allow screen reader users to continue to confirm their file selection, we should move the file status from the aria-label to a dynamically created sr-only element.

Major changes

Moved the file status update from the input aria-label to a new sr-only element.
The input aria-label now matches the visible instruction text so that voice command users can access the component with intuitive commands
Broke out buildFileInput() into separate functions: createTargetArea and createVisibleInstructions
Standardized and added clarity to JSDoc comments

Possible future enhancements

Converting the CTA text ("choose from folder", "change file") from a <span> element to a <button> element might improve consistency in Voice Command software. It could also give an alternative method for voice control users so that they can highlight all interactive elements on the page and select the element they want to click.

Testing and review

Accessibility:

Confirm that the screen reader experience is intuitive and makes sense
Confirm that you can open the file input dialog via voice command (If available. It would be helpful to know which tools you used)
When file status changes, confirm that the status update is read on a screen reader

Developers:

The following items should be confirmed:

Confirm that the aria-label on the input matches the visible instruction text:
- Default text = “Drag file here or choose from folder”
- One file selected = “Change file”
- More than one file selected = “Change files”
- File removed = “Drag file here or choose from folder”
Confirm that the status element (.usa-sr-only) updates correctly when:
- One file selected = "You have selected the file: [fileName]"
- More than one file selected = "You have selected [x] files: [fileName], [fileName], etc"
- File removed = "No file selected."
In the multiple inputs test page, confirm that each input creates unique status update.
Confirm no visual regressions
Confirm no behavioral regressions
Confirm the JavaScript is well-structured and makes sense
[ADDITION] Confirm that status element is not created for disabled or aria-disabled file inputs

…ons to let at top of function

… to removeOldPreviews params

amyleadem · 2023-04-18T21:29:29Z

@briandeconinck I have created a prototype here that changes the aria-label on the file input to match the visible instruction text ("Drag file here or choose from folder").

This is still a work in progress but before I get too far down the road, would you be able to test this prototype to see if you can access the input by speaking the visible text via Dragon Naturally Speaking (and/or any other voice control software you might have access to)?

Please let me know if you have questions!

briandeconinck · 2023-04-24T21:40:59Z

Hi Amy! Sorry for the slow reply.

I see the updated aria-label and I believe it should work... but when I actually test it, it's hit-or-miss. Digging through some 7+ year old forum threads and it sounds like there's some inconsistency with how Dragon plays with file inputs. But the aria-label is giving me a match at least some of the time, with both the full text and just the "choose from folder" substring. Accounting for odd behavior with Dragon, that might be good enough. 🤷

I will note that since the instruction text has the fake-link styling, the command "Click link" still doesn't highlight the input as an option, which would typically be the next thing I try if "Click choose from folder" doesn't get a match. Maybe make it an actual link or button with a JS action to map it to the input? I believe even if it's removed from the tab order with tabindex="-1" it should still work with Dragon, but I haven't tested that.

Up to you whether you want to pursue that. What you have here is definitely an improvement and should work most of the time for Dragon users (again, accounting for possible Dragon weirdness).

amyleadem · 2023-04-25T18:19:48Z

Thanks for the response, @briandeconinck! Your test results are helpful. Since we aren't hitting consistent results with aria-label in Dragon and other voice command methods, I am going to explore if there are alternate paths here. Thanks for the suggestions and I appreciate you taking the time! I'll tag you again if there are any updates.

amyleadem · 2023-05-17T22:56:44Z

Note: considering removing the SR-only element readout if file input is disabled. Might determine that no action is needed or it could be a follow-up issue. Will investigate tomorrow. There is no need for this effort to interrupt any reviews in process.

amyleadem · 2023-05-18T21:57:21Z

I added a check for the disabled attribute before generating the sr-only status message. Let me know if you see any issues with this.

mejiaj

Focused on code in this review and added some comments. Overall no issues, but some minor areas we can improve.

Mainly, saving the default aria label in code and possible duplicate check on disabled state.

packages/usa-file-input/src/index.js

mejiaj · 2023-05-19T19:50:15Z

packages/usa-file-input/src/index.js


  // Adds class names and other attributes
  fileInputEl.classList.remove(DROPZONE_CLASS);
  fileInputEl.classList.add(INPUT_CLASS);
  fileInputParent.classList.add(DROPZONE_CLASS);
  box.classList.add(BOX_CLASS);
-  instructions.classList.add(INSTRUCTIONS_CLASS);
-  instructions.setAttribute("aria-hidden", "true");
  dropTarget.classList.add(TARGET_CLASS);


Minor, but for clarity you could remove line 163 and place box inside of dropTarget instead of fileInputEl.parentNode.

Suggested change

dropTarget.classList.add(TARGET_CLASS);

dropTarget.classList.add(TARGET_CLASS);

dropTarget.prepend(box);

Updated in e102337
Note: This does reorder usa-file-input__box and usa-file-input__instructions, but it does not seem to have an impact since both elements already had z-index set in their styles.

Gotcha, thanks for that explanation. My main concern was lack of clarity when it came time to adding all the DOM elements and seeing what went where.

mejiaj · 2023-05-19T20:13:18Z

packages/usa-file-input/src/index.js

+  if (!disabled) {
+    createSROnlyStatus(fileInputEl);
+  }


There's some code that also checks for disabled/aria-disabled in createTargetArea(). Could any of that be moved in this check?

Code in createTargetArea():

uswds/packages/usa-file-input/src/index.js

Lines 165 to 173 in 0843926

// Disabled styling

if (disabled) {

disable(fileInputEl);

}

// Aria-disabled styling

if (ariaDisabled) {

ariaDisable(fileInputEl);

}

Moved disabled checks into enhanceFileInput() in cd6ba70

packages/usa-file-input/src/index.js

mejiaj · 2023-05-19T20:28:09Z

packages/usa-file-input/src/index.js

 */
-const buildFileInput = (fileInputEl) => {
+const setItemsLabel = (fileInputEl) => {


This doesn't seem to set anything, maybe we could clarify with getItemsLabel or something more descriptive.

Suggested change

const setItemsLabel = (fileInputEl) => {

const getItemsLabel = (fileInputEl) => {

Good catch. Updated in 38cf451

mejiaj · 2023-05-19T20:38:32Z

packages/usa-file-input/src/index.js

+
+  // Add initial instructions for input usage
+  fileInputEl.setAttribute("aria-label", defaultInstructionsText);
+  fileInputEl.setAttribute("data-default-aria-label", defaultInstructionsText);


Could we reuse defaultInstructionsText instead of setting it as a data attribute?

Thanks for the tip! Created global variables to replace data-default-aria-label in 659d51a and data-default-status-text in af2a72b.

mejiaj · 2023-05-19T20:50:26Z

packages/usa-file-input/src/index.js

@@ -184,17 +210,60 @@ const buildFileInput = (fileInputEl) => {
    fileInputParent.querySelector(`.${DRAG_TEXT_CLASS}`).outerHTML = "";
  }


Future task

We could remove this IE11/Edge check any time.

HTMLElement: drop event - Web APIs | MDN

mejiaj · 2023-05-22T13:52:08Z

packages/usa-file-input/src/index.js

+  }
+
+  // Hides null state content and sets preview heading
+  instructions.classList.add(HIDDEN_CLASS);


Small, but we have this HIDDEN_CLASS defined on line 21. An alternative would be to use the hidden attribute, like accordion. Would be one less const to manage.

Replaced HIDDEN_CLASS in favor of the hidden attribute in 4278f23

Co-authored-by: James Mejia <james.mejia@gsa.gov>

Updated to improve clarity

…o al-file-input-vc

amyleadem

@mejiaj Thanks for the helpful review! I have addressed all comments. Please let me know if you have questions.

amyleadem · 2023-05-22T16:14:59Z

packages/usa-file-input/src/index.js


  // Adds class names and other attributes
  fileInputEl.classList.remove(DROPZONE_CLASS);
  fileInputEl.classList.add(INPUT_CLASS);
  fileInputParent.classList.add(DROPZONE_CLASS);
  box.classList.add(BOX_CLASS);
-  instructions.classList.add(INSTRUCTIONS_CLASS);
-  instructions.setAttribute("aria-hidden", "true");
  dropTarget.classList.add(TARGET_CLASS);


Updated in e102337
Note: This does reorder usa-file-input__box and usa-file-input__instructions, but it does not seem to have an impact since both elements already had z-index set in their styles.

amyleadem · 2023-05-22T22:04:03Z

packages/usa-file-input/src/index.js

+  if (!disabled) {
+    createSROnlyStatus(fileInputEl);
+  }


Moved disabled checks into enhanceFileInput() in cd6ba70

amyleadem · 2023-05-22T22:04:20Z

packages/usa-file-input/src/index.js

+  }
+
+  // Hides null state content and sets preview heading
+  instructions.classList.add(HIDDEN_CLASS);


Replaced HIDDEN_CLASS in favor of the hidden attribute in 4278f23

amyleadem · 2023-05-22T22:05:44Z

packages/usa-file-input/src/index.js

+
+  // Add initial instructions for input usage
+  fileInputEl.setAttribute("aria-label", defaultInstructionsText);
+  fileInputEl.setAttribute("data-default-aria-label", defaultInstructionsText);


Thanks for the tip! Created global variables to replace data-default-aria-label in 659d51a and data-default-status-text in af2a72b.

amyleadem · 2023-05-22T22:06:18Z

packages/usa-file-input/src/index.js

 */
-const buildFileInput = (fileInputEl) => {
+const setItemsLabel = (fileInputEl) => {


Good catch. Updated in 38cf451

On enhance file input will add a class if the component either has aria-disabled or disabled attribute.

amyleadem · 2023-05-23T22:58:28Z

@mejiaj I confirmed that your update adds the disabled class as expected when either disabled or aria-disabled is present on the input element. Thanks for cleaning up the disabled behavior so that the attributes aren't touched on init. Appreciate it!

Will you let me know if you see anything else?

mejiaj

Code looks good, I just have a comment on addPreviewHeading(). This function adds a description for screen readers for how many files and their names.

On voiceover this only gets read once after upload. We could improve this by having it be read on focus as a fast follow-up.

mejiaj · 2023-05-24T16:11:09Z

packages/usa-file-input/src/index.js

+ * @param {HTMLInputElement} fileInputEl - The input element.
+ * @param {Object} fileNames - The selected files found in the fileList object.
+ */
+const addPreviewHeading = (fileInputEl, fileNames) => {


This function adds text describing:

How many files

Which files have been uploaded

So far I've only gotten it to read after initial upload. If I move to another area and comeback it doesn't get read on VoiceOver Chromium 113.

Possible Future enhancements:

Add a unique ID to this message and tie it to the component via aria-labelledby [MDN on aria-labelledby]

Move the preview heading text so it always gets read.

Dynamically update the aria-label

Move the preview heading text example

file-input-label.mp4

Thanks @mejiaj. I've opened #5304 to start looking into this. I will begin investigating as a fast follow-up.

thisisdano

Nice work

amyleadem added 13 commits April 3, 2023 09:56

Create status message element; add default message

1432fc1

Update status message in handleChange

24f7239

Find statusMessage from dropTarget

4fc3d8f

Add instruction text to input aria-label

a8ea6f8

Update sr-only-class

2103bf7

On change, set input aria-label to match visible instruction text

57c4e8c

Run prettier

81a8f82

Add clarifying comments to buildFileInput; move lower const declarati…

c408be7

…ons to let at top of function

Small cleanup

973eda2

Add setTimeout to status element; add statusElement and statusMessage…

dc2d66d

… to removeOldPreviews params

Add conditional to removeOldPreviews to prevent unit test error

c978289

Add status message tests to unit test

b3aaf22

Run prettier

7a4d917

amyleadem changed the title ~~USWDS - File input: Fix issues with voice comman~~ USWDS - File input: Fix issues with voice command Apr 5, 2023

amyleadem added 11 commits April 7, 2023 15:22

Update comments

f7fb830

Use aria-describedby

6423b25

Create multiple inputs test story

4f6ae5b

Disconnect aria-describedby from status message; update comments

1ab3096

Add story demonstrating data attributes

ecacad2

Set text with data attributes, if available

10476b5

Update unit tests

e02cd77

Formatting

8157249

Update data-default-status-message to data-default-status-text

012e01b

Remove custom text data attributes. Will address in future issue

a5c8196

Update dragText to fix unit test

6eece6d

amyleadem added 2 commits May 4, 2023 11:38

Move multiple inputs test into /test-patterns directory

e3b5022

Remove multiple_inputs arg from stories.js

a1a3d0a

amyleadem requested a review from mejiaj May 10, 2023 22:00

amyleadem added 3 commits May 17, 2023 16:11

Merge develop; resolve merge conflicts in index.js and stories.js

7c6c21a

Run prettier

f253f6a

Add check for disabled state before creating sr-only status

0843926

mejiaj requested changes May 22, 2023

View reviewed changes

amyleadem mentioned this pull request May 22, 2023

USWDS - JavaScript Enhancement: Improve consistency of component "get elements" functions #5299

Open

amyleadem and others added 9 commits May 22, 2023 08:35

Rename setItemsLabel --> getItemsLabel

38cf451

Simplify comments for createVisibleInstructions

ec606b8

Co-authored-by: James Mejia <james.mejia@gsa.gov>

Add box to dropTarget instead of the input parent

e102337

Updated to improve clarity

Add DEFAULT_ARIA_LABEL_TEXT to remove need for data-default-aria-label

659d51a

Merge branch 'al-file-input-vc' of https://github.com/uswds/uswds int…

8e5dcf3

…o al-file-input-vc

Add DEFAULT_FILE_STATUS_TEXT to remove need for data-default-status-text

af2a72b

Move disabled checks from createTargetArea to enhanceFileInput

cd6ba70

Remove HIDDEN_CLASS in favor of hidden attribute

4278f23

Run prettier

8dbf2e1

amyleadem commented May 22, 2023

View reviewed changes

amyleadem requested a review from mejiaj May 22, 2023 22:12

Simplify check for disabled component

bb7a9d6

On enhance file input will add a class if the component either has aria-disabled or disabled attribute.

mejiaj approved these changes May 24, 2023

View reviewed changes

amyleadem mentioned this pull request May 24, 2023

USWDS - File input: Improve file status readout for screen readers #5304

Open

amyleadem requested a review from thisisdano May 24, 2023 17:01

thisisdano mentioned this pull request May 25, 2023

Add changelog items for USWDS 3.5.0 uswds/uswds-site#2096

Merged

24 tasks

thisisdano approved these changes May 26, 2023

View reviewed changes

thisisdano merged commit 2c6dcfa into develop May 26, 2023

thisisdano deleted the al-file-input-vc branch May 26, 2023 20:21

thisisdano mentioned this pull request Jun 6, 2023

USWDS 3.5.0 #5323

Merged

rsmithadhoc mentioned this pull request Nov 7, 2023

USWDS - File Input - Design department-of-veterans-affairs/vets-design-system-documentation#1499

Closed

14 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS - File input: Fix issues with voice command #5213

USWDS - File input: Fix issues with voice command #5213

amyleadem commented Apr 3, 2023 •

edited

Loading

amyleadem commented Apr 18, 2023 •

edited

Loading

briandeconinck commented Apr 24, 2023

amyleadem commented Apr 25, 2023

amyleadem commented May 17, 2023 •

edited

Loading

amyleadem commented May 18, 2023 •

edited

Loading

mejiaj left a comment

mejiaj May 19, 2023

amyleadem May 22, 2023

mejiaj May 23, 2023

mejiaj May 19, 2023

amyleadem May 22, 2023

mejiaj May 19, 2023

amyleadem May 22, 2023

mejiaj May 19, 2023

amyleadem May 22, 2023

mejiaj May 19, 2023

mejiaj May 22, 2023

amyleadem May 22, 2023

amyleadem left a comment

amyleadem May 22, 2023

amyleadem May 22, 2023

amyleadem May 22, 2023

amyleadem May 22, 2023

amyleadem May 22, 2023

amyleadem commented May 23, 2023

mejiaj left a comment

mejiaj May 24, 2023

amyleadem May 24, 2023

thisisdano left a comment

	dropTarget.classList.add(TARGET_CLASS);
	dropTarget.classList.add(TARGET_CLASS);
	dropTarget.prepend(box);

	// Disabled styling
	if (disabled) {
	disable(fileInputEl);
	}

	// Aria-disabled styling
	if (ariaDisabled) {
	ariaDisable(fileInputEl);
	}

	const setItemsLabel = (fileInputEl) => {
	const getItemsLabel = (fileInputEl) => {

		@@ -184,17 +210,60 @@ const buildFileInput = (fileInputEl) => {
		fileInputParent.querySelector(`.${DRAG_TEXT_CLASS}`).outerHTML = "";
		}

USWDS - File input: Fix issues with voice command #5213

USWDS - File input: Fix issues with voice command #5213

Conversation

amyleadem commented Apr 3, 2023 • edited Loading

Summary

Breaking change

Related issue

Related pull requests

Preview link

Problem statement

Voice command issues

Screen readers issues

Solution

Major changes

Possible future enhancements

Testing and review

Accessibility:

Developers:

amyleadem commented Apr 18, 2023 • edited Loading

briandeconinck commented Apr 24, 2023

amyleadem commented Apr 25, 2023

amyleadem commented May 17, 2023 • edited Loading

amyleadem commented May 18, 2023 • edited Loading

mejiaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Future task

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amyleadem commented May 23, 2023

mejiaj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Possible Future enhancements:

Choose a reason for hiding this comment

thisisdano left a comment

Choose a reason for hiding this comment

amyleadem commented Apr 3, 2023 •

edited

Loading

amyleadem commented Apr 18, 2023 •

edited

Loading

amyleadem commented May 17, 2023 •

edited

Loading

amyleadem commented May 18, 2023 •

edited

Loading