USWDS - Input Mask: (Error Feedback) Code Refactor

[mlloydbixal]

Summary

Improve invalid character feedback with error message. Add error messages (customizable via data attributes) to give proper user feedback when an invalid character is not added to the input value.

Breaking change

This is not a breaking change however there two minor warnings to note:

• This update adds an error message string below input masks which could result in a small shift in content.
• For sites with translated content: this update adds error message strings in english only.

Related issue

Closes #5481

Related Pull Request

USWDS-Site: Add changelog for input mask [#6203]

Preview link

Preview link

Problem statement

The current state of the input mask component does not provide any audio feedback and very little visual feedback to the user that the character they attempted to add to the input value was rejected. Usability testing showed they were often unaware that the characters were not allowed. The desired state would be feedback to the user via an error message and the appropriate aria-labels that offer context that their input was rejected, what the current state of the input now is, and what the input is expecting from them. This issue affects every user.

Solution

The solution is to provide an error message that is descriptive and dynamic enough so that it updates the user on what the input mask is expecting of them whether it is a letter or a number. Additional aria labeling will provide the same context to screen readers in a message that can be customized separately to give additional instruction if necessary.

Testing and review

Navigate to text input mask component (alphanumeric is best for testing all the error message types at once but the others should still be tested for regression)

1. Tab into input, no error should display
2. Type “A” displays no error
3. Type “AB” displays “You must enter a number”
4. Type “A1” displays no error
5. Type “A12” displays “You must enter a letter”
6. Type “A1B” displays no error
7. Finishing input with “A1B 2C3” displays no error
8. Continuing to type displays error “You have reached the maximum number of characters allowed”
9. BACKSPACE clears the error
10. ARROW LEFT and ARROW RIGHT do not trigger an error
11. CMD + BACKSPACE clears the input with no error displayed
12. Pasting “A1B2C3” formats text and displays no error
    *Paste tests should only be done with keyboard, issues with paste click events will be covered in a seperate issue
13. Pasting “A1B2222” displays “Some pasted characters were not accepted.”
14. Using navigational keys do not display an error: HOME, END, ARROW LEFT, ARROW RIGHT, PAGE UP, PAGE DOWN, TAB
15. When testing using a screen reader the error message should be read to user 1000ms after the error message displays. This message should be able to be customized separately from the one displayed visually.

*When error message does not display it should also be hidden with no visual padding or styling
*There should be no regressions or changes to mask functionality outside of partial improvements to paste functionality. This is only an error message enhancement.

[mejiaj]

Overall this is looking good! I've only tested the functionality so far. Please don't forget to create unit tests.

Discovered a minor quirk in special characters.

For example
Enter ! the error will flash and disappear, but if you enter = it will stay. Attached GIF below.

[mlloydbixal]

@mejiaj thanks for the draft feedback! Good catch on that bug :O

[mlloydbixal]

Overall this is looking good! I've only tested the functionality so far. Please don't forget to create unit tests.

Discovered a minor quirk in special characters.

For example Enter ! the error will flash and disappear, but if you enter = it will stay. Attached GIF below.

I think it has something to do with holding down the shift button. I will add this edge case - good catch!

[mlloydbixal]

I'm working on refining the error message so that a screen reader user understands their invalid character was not added to the input. There was some confusion from users if they needed to backspace or not (and they don't need to). I'm wondering if updating the message to say "Error: please enter a number. Your last entry was not added to the value." is descriptive enough OR if we need to adjust functionality to read them back their whole input like "Error: please enter a number. Currently the input value is "a1b 2c"

I notice in VO it reads the new full input value after a character has been accepted, but not when it's rejected.

Thoughts?
@amyleadem @amycole501

[amycole501]

I prefer your second wording. And in JAWS typically nothing is read aloud for me unless I backspace to hear it. Most JAWS and NVDA users I suspect will be used to arrowing backwards to hear each character. That said, hearing the entire data field announced sounds like a great enhancement!

[mlloydbixal]

@mejiaj The navigational bugs are fixed in 5ca978f and the styling issue fixed in d5e195f

[mahoneycm]

Found a couple more behavior issues while testing screen readers! Also going to take a quick look at unit tests to see if I can help get them unblocked

[mejiaj]

@mlloydbixal thanks for all your work on this so far. The previous special character and keyboard combination issues have been fixed.

What I tested

• Error message visual issues
• Special characters and navigation keys are fixed
• Paste shows an error if input is incorrect

Additionally added comments for code style and suggestions for clarity.