USWDS - Input Mask: (Error Feedback) Code Refactor #6203

mlloydbixal · 2024-11-13T19:05:38Z

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

Indicate if this update is a breaking change with one of the following statements:
This is not a breaking change.
⚠️ This is potentially a breaking change.
⚠️ This is a breaking change.

Related issue

Closes #5481

Related Pull Request

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

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 the 3 error message types)
Trigger error message by typing in the wrong input
Confirm the message shown is relevant to the input that the mask is requiring
Repeat this for both numbers and letters to trigger both message types
Test using special characters
When correctly completing the input - no error message should be present. Now continue to type to trigger the message "Maximum character count reached".
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.

*There should be no regressions or changes to mask functionality. This is only an error message enhancement.

packages/usa-input-mask/src/usa-input-mask.twig

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.

packages/usa-error-message/src/styles/_usa-error-message.scss

mejiaj · 2024-11-19T21:04:21Z

packages/usa-input-mask/src/usa-input-mask.twig

+      {% if dataErrorMessage %}data-errormessage="{{ dataErrorMessage }}"{% endif %}
+      {% if dataErrorAlphabetical %}data-errormessage-alpha="{{ dataErrorAlphabetical }}"{% endif %}
+      {% if dataErrorNumerical %}data-errormessage-num="{{ dataErrorNumerical }}"{% endif %}


There was some discussion related to the correct name for this in File input PR #6168 ¹.

The TL;DR is that there's an established naming convention of using something like data-errorMessage. While not a fan of it because it seems unconventional to other USWDS settings, maybe we should use for consistency in error messages.

Footnotes

https://github.com/uswds/uswds/pull/6168#discussion_r1842880357 ↩

Fixed in c4bfd9b (I think I got it right but the thread was a little confusing to follow, let me know if I should make any adjustments)

mlloydbixal · 2024-11-20T13:39:34Z

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

mlloydbixal · 2024-11-21T14:58:29Z

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 · 2024-11-21T21:00:08Z

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 · 2024-11-22T14:23:39Z

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!

mejiaj · 2024-12-03T21:27:55Z

@mlloydbixal can you please look into the build errors?

cathybaptista · 2024-12-04T23:03:55Z

Hi, @mlloydbixal!

I realize you didn't officially request that I review this, but I checked it out anyway. I noticed the issues that James already pointed out, plus when I entered "A" in the alphanumeric field, it showed me an error, probably for the same reason as you mentioned, the shift key. Whatever this is it is also causing this... if you enter a lowercase letter in the same variant that's fine, but then if you enter a $ or some other special character, I am getting the error message Maximum character count reached, and I don't think that's right? If I enter a lowercase letter and then another lc letter I get please enter a number. If you hold down the shift key I can see the right message in Firefox or Arc.

I also am not a UI guru (and certainly not for USWDS), but is the error message too close to the input? Also, how do we feel about the language "Error:" we use "Maximum character count reached" so is that OK for the others? Like Please enter a number and not Error: please enter a number? Just my two cents. ;)

mlloydbixal · 2024-12-05T18:06:56Z

@cathybaptista thanks for giving it a test! That was a regression caused earlier this week after satisfying lint errors..ugh. I fixed it this morning if you want to take a second look.

Also - regarding your last comment - adding "Error:" to those messages was a request from @amycole501 per an earlier discussion. I didn't think it's necessary to also add it to "Maximum character count reached" because it's not really an error or something that needs to be corrected. That message is just letting the user know they can't add anymore characters. @jaclinec @alex-hull any thoughts on that wording? The preview link in the PR is up to date with all bugs solved if you'd like to see the message types.

mlloydbixal · 2024-12-05T21:58:02Z

@mejiaj @amyleadem @mahoneycm ready for re-review 🥳

mlloydbixal · 2024-12-06T02:18:43Z

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.

Bug was resolved in 81f10da and again in 616c6e3 after a regression

jaclinec · 2024-12-06T15:29:22Z

@cathybaptista thanks for giving it a test! That was a regression caused earlier this week after satisfying lint errors..ugh. I fixed it this morning if you want to take a second look.

Also - regarding your last comment - adding "Error:" to those messages was a request from @amycole501 per an earlier discussion. I didn't think it's necessary to also add it to "Maximum character count reached" because it's not really an error or something that needs to be corrected. That message is just letting the user know they can't add anymore characters. @jaclinec @alex-hull any thoughts on that wording? The preview link in the PR is up to date with all bugs solved if you'd like to see the message types.

I agree that we probably don't need to use "error" for maximum character count reached since, as you said, it's more informational rather than something they need to fix. But it does make sense to use "error" in the message when they type an invalid character (like a letter instead of a number) since they'll need to fix the error.

cathybaptista · 2024-12-06T20:29:25Z

@mlloydbixal and @jaclinec Sounds good to me! This is looking awesome! :)

While I was confirming, I did find one thing you might just want to check... if I go to Alphnumeric, enter a letter (no problems) and then enter a special character (I tried this with the space bar and the control key), I get an Error: Please Enter a Letter message. If I follow that message, I get "Error: please enter a number", which is right. Here is a vid... showing the space and then the letter:

Screen.Recording.2024-12-06.at.3.24.29.PM.mov

:)
Cathy

mlloydbixal · 2024-12-06T20:37:03Z

@cathybaptista can you test again using the "open canvas in new tab" button? I think because of the way we have a double compile in the build sometimes updates lag behind when you are testing inside the storybook window. If I test inside the storybook window I see even worse results than what you shared. Try going to this preview link or locally. Sorry for the confusion :)

mlloydbixal added 8 commits November 7, 2024 12:20

add error message span to usa-input-mask

778381b

update id

5a678fb

allow dynamic id with getcontext function

aef8a7a

change var name

4395f46

change error message based on requirement

136f1f9

separate error handling logic froom handleCurrentValue function

2966f8f

make check for what mask expects

09aa8e5

clean up code

c77d00f

mlloydbixal commented Nov 13, 2024

View reviewed changes

packages/usa-input-mask/src/usa-input-mask.twig Show resolved Hide resolved

mlloydbixal added 3 commits November 13, 2024 14:09

keep original comment

234cfc8

revert conditional

f9866d3

fix lint errors

112c0f4

mlloydbixal changed the title ~~Input Mask (Error Feedback) Refactor~~ USWDS - Input Mask: (Error Feedback) Code Refactor Nov 15, 2024

run prettier

3fd6c08

mejiaj reviewed Nov 19, 2024

View reviewed changes

mlloydbixal added 2 commits November 21, 2024 09:40

remove css change, use js attribute

92ff587

update naming conventions

c4bfd9b

handle edge case bug for special characters

81f10da

add error for max char count

4967e3b

mlloydbixal added 7 commits November 27, 2024 12:57

add max char count and sr-only error messages

9c49c3f

solve max length bug

b786a7b

add visual error message unit test

bf6eea9

fix max character count reached bug

3b55e4a

direct screen reader to read sronly message only

f86ee8a

create spans using js, rm from template markup

fa589bb

use debounce on sr message update

a6dded5

mlloydbixal added 8 commits November 29, 2024 20:02

improve readability

2096a97

resolve lint errors

726d2c4

fix format character bug

22f35c8

revert lint fix

83f5c64

adjust debounce

a38051e

debounce for text content separately

2918a22

remove error spans before recreating them

9b4901f

rm comment

b972750

mlloydbixal requested review from mejiaj, mahoneycm and amyleadem December 2, 2024 20:56

mlloydbixal marked this pull request as ready for review December 2, 2024 20:59

mlloydbixal requested a review from a team as a code owner December 2, 2024 20:59

fix regression

616c6e3

mlloydbixal added 2 commits December 5, 2024 15:09

fix bug when user types quickly

f8ee66e

run prettier --write

6a07919

mlloydbixal mentioned this pull request Dec 6, 2024

USWDS-Site: Add changelog for input mask [#6203] uswds/uswds-site#3001

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS - Input Mask: (Error Feedback) Code Refactor #6203

USWDS - Input Mask: (Error Feedback) Code Refactor #6203

mlloydbixal commented Nov 13, 2024 •

edited

Loading

mejiaj left a comment •

edited

Loading

mejiaj Nov 19, 2024

mlloydbixal Dec 6, 2024 •

edited

Loading

mlloydbixal commented Nov 20, 2024

mlloydbixal commented Nov 21, 2024

mlloydbixal commented Nov 21, 2024 •

edited

Loading

amycole501 commented Nov 22, 2024

mejiaj commented Dec 3, 2024

cathybaptista commented Dec 4, 2024

mlloydbixal commented Dec 5, 2024 •

edited

Loading

mlloydbixal commented Dec 5, 2024

mlloydbixal commented Dec 6, 2024

jaclinec commented Dec 6, 2024

cathybaptista commented Dec 6, 2024

mlloydbixal commented Dec 6, 2024

USWDS - Input Mask: (Error Feedback) Code Refactor #6203

Are you sure you want to change the base?

USWDS - Input Mask: (Error Feedback) Code Refactor #6203

Conversation

mlloydbixal commented Nov 13, 2024 • edited Loading

Summary

Breaking change

Related issue

Related Pull Request

Preview link

Problem statement

Solution

Testing and review

mejiaj left a comment • edited Loading

Choose a reason for hiding this comment

mejiaj Nov 19, 2024

Choose a reason for hiding this comment

Footnotes

mlloydbixal Dec 6, 2024 • edited Loading

Choose a reason for hiding this comment

mlloydbixal commented Nov 20, 2024

mlloydbixal commented Nov 21, 2024

mlloydbixal commented Nov 21, 2024 • edited Loading

amycole501 commented Nov 22, 2024

mejiaj commented Dec 3, 2024

cathybaptista commented Dec 4, 2024

mlloydbixal commented Dec 5, 2024 • edited Loading

mlloydbixal commented Dec 5, 2024

mlloydbixal commented Dec 6, 2024

jaclinec commented Dec 6, 2024

cathybaptista commented Dec 6, 2024

mlloydbixal commented Dec 6, 2024

mlloydbixal commented Nov 13, 2024 •

edited

Loading

mejiaj left a comment •

edited

Loading

mlloydbixal Dec 6, 2024 •

edited

Loading

mlloydbixal commented Nov 21, 2024 •

edited

Loading

mlloydbixal commented Dec 5, 2024 •

edited

Loading