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. Closes #5482.

Related Pull Request

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

Preview link

Preview link

Problem statement

Previously, the input mask component provided minimal visual feedback and no auditory feedback when users attempted to enter an invalid character. Usability testing revealed that users were often unaware that their input was rejected. The goal was to provide clear, accessible feedback through error messages and ARIA attributes, ensuring users understood why their input was rejected and what was expected instead.

Solution

This solution introduced descriptive, dynamic error messages that informed users about invalid inputs and clarified what was expected, whether a letter or a number. Additionally, enhanced ARIA labeling ensured screen readers conveyed the same feedback, with customizable messages that could provide further guidance if needed.

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!

[mahoneycm]

Getting really close! I'm still unable to see the error message on paste and there's one small code polish improvement we can make then it's just onto the unit tests!

Thanks Mandy

[mahoneycm]

thought: I'm not familiar with the best practice for JSdocs with multiple returns but since this is an object we could use one return and just describe the object returned.

Suggested change

	* @return {string} newValue - The full input value after the most recent character is added or rejected.
	* @return {string} matchType - The required character type (e.g., 'letter' or 'number') for the current position in the mask.
	* @return {object} newValue and matchType strings - The updated value string and matchType for the current position in the mask

[mahoneycm]

Note that this appears to be closer to how we use JSDocs when larger objects are returned, like our "get context" functions (though this example could use some more detail):

uswds/packages/usa-combo-box/src/index.js

Lines 72 to 79 in f2963d8

	/**
	* Get an object of elements belonging directly to the given
	* combo box component.
	*
	* @param {HTMLElement} el the element within the combo box
	* @returns {ComboBoxContext} elements
	*/
	const getComboBoxContext = (el) => {

[mlloydbixal]

From what I read, the way it is is considered acceptable. An alternative would be something like:

@typedef {object} MaskResult
@property {string} newValue - The full input value after the most recent character is added or rejected.
@property {string} matchType - The required character type (e.g., 'letter' or 'number') for the current position in the mask.
@return {MaskResult}

Any preference?? cc @mejiaj @amyleadem

[mahoneycm]

I'm still able to paste invalid characters with the keyboard paste without triggering the error state.

Kapture.2025-02-05.at.13.17.25.webm

It looks like this snippet of code is not being run on paste:

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

Lines 309 to 311 in a8775d6

	if (newValue.length !== len && inputAddedByPaste) {
	newValue = stripPasteValue(newValue, clipboardData);
	}

[mahoneycm]

It seems rare and not important enough to block! I say we press on for now and if it continues to appear we can look into it down the line

[dct2023]

@mahoneycm This is ready for your review.