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

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

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)
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
shift key to capitalize
navigational keys (Home, End, ←, →, Page up/down)
backspace and cmd + backspace
paste

When correctly completing the input - no error message should be present. Continue to type to trigger the message "Maximum character count reached".
Backspacing should clear error messages
When using paste and only part or none of what is copied to clipboard is accepted, an error message should display
When using paste and the full clipboard was accepted, no error message should display
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

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

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!

mlloydbixal · 2025-01-09T17:48:18Z

@mlloydbixal running into an issue on Alphanumeric where sometimes it'll show an incorrect error on SHIFT+A

Added a check for key combos in 8ac4c2a 👍

mahoneycm

Great work here @mlloydbixal ! I left some requests but it's mostly just polish and cleanup work.

Fuctionaly, this feels very close!

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

mahoneycm · 2025-01-09T20:29:32Z

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

+const ERROR_MESSAGE_DEFAULT = "Error: please enter a valid character";
+const ERROR_MESSAGE_SR_DEFAULT = "Error: please enter a valid character";
+const ERROR_MESSAGE_FULL_DEFAULT = "Maximum character count reached";
+const ERROR_MESSAGE_FULL_SR_DEFAULT = "Maximum character count reached";
+const ERROR_MESSAGE_ALPHA_DEFAULT = "Error: please enter a letter";
+const ERROR_MESSAGE_ALPHA_SR_DEFAULT = "Error: please enter a letter";
+const ERROR_MESSAGE_NUMERIC_DEFAULT = "Error: please enter a number";
+const ERROR_MESSAGE_NUMERIC_SR_DEFAULT = "Error: please enter a number";


question: Do we need duplicates of all of these? Since they match can we just use the default values?

Suggested change

const ERROR_MESSAGE_DEFAULT = "Error: please enter a valid character";

const ERROR_MESSAGE_SR_DEFAULT = "Error: please enter a valid character";

const ERROR_MESSAGE_FULL_DEFAULT = "Maximum character count reached";

const ERROR_MESSAGE_FULL_SR_DEFAULT = "Maximum character count reached";

const ERROR_MESSAGE_ALPHA_DEFAULT = "Error: please enter a letter";

const ERROR_MESSAGE_ALPHA_SR_DEFAULT = "Error: please enter a letter";

const ERROR_MESSAGE_NUMERIC_DEFAULT = "Error: please enter a number";

const ERROR_MESSAGE_NUMERIC_SR_DEFAULT = "Error: please enter a number";

const ERROR_MESSAGE_DEFAULT = "Error: please enter a valid character";

const ERROR_MESSAGE_FULL_DEFAULT = "Maximum character count reached";

const ERROR_MESSAGE_ALPHA_DEFAULT = "Error: please enter a letter";

const ERROR_MESSAGE_NUMERIC_DEFAULT = "Error: please enter a number";

(would need to update where the SR values are used)

Part of an earlier discussion (may not have been tracked on this PR thread) was having the option to use different messages for screen readers so it can be more descriptive when needed. Users who can see the visual message don't need as detailed of a message. I'll get with the team about what the SR messages should be so the difference is more obvious! 👍

Hey Mandy, just checking back in on this as part of my re-review! Are we sure there are use cases where we want screen readers to have a different error message than the visual error message?

If so we can limit the amount of code maintained by relying on the same default and updating where necessary:

const ERROR_MESSAGE_DEFAULT = "Error: please enter a valid character"; - const ERROR_MESSAGE_SR_DEFAULT = "Error: please enter a valid character"; // later const errorMsgSrOnly = - inputEl.getAttribute("data-errorMessageSrOnly") || ERROR_MESSAGE_SR_DEFAULT; + inputEl.getAttribute("data-errorMessageSrOnly") || ERROR_MESSAGE_DEFAULT;

This would use the same default error message but still allow users to override with data-errorMessageSrOnly

@amyleadem can you weigh in on this? I think you began the original discussion way back when. Charlie's suggestion would mean less code to maintain but would rely on users to improve the instructions offered to screen reader users.

I'm working with @jaclinec to nail down the error messages text content but currently the only difference between the visual message and SR only messages is the use of "Error: " which was a request by @amycole501.

Example:

const ERROR_MESSAGE_FULL_DEFAULT = "You have reached the maximum number of characters allowed"; const ERROR_MESSAGE_FULL_SR_DEFAULT = "Error: You have reached the maximum number of characters allowed."; const ERROR_MESSAGE_ALPHA_DEFAULT = "You must enter a letter"; const ERROR_MESSAGE_ALPHA_SR_DEFAULT = "Error: You must enter a letter";

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

mahoneycm · 2025-01-09T20:49:57Z

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

+    default:
+      errorMessageEl.textContent = errorMsg;
+      srUpdateErrorMsg(errorMessageSrOnlyEl, errorMsgSrOnly);


question: I'm curious when we'd want this default message to come up. Is this just used as a failsafe?

note: I was able to trigger this by rapidly entering multiple characters when the input was empty. I expected "please enter a number" error message but I don't think this needs to be a blocker for this work.

Kapture.2025-01-09.at.15.48.31.webm

Yes I had it originally to make troubleshooting more obvious (if it fell back to default I knew something was probably wrong vs it being wrong but not noticing because it accidentally used the correct messaging.. sometimes two wrongs would make a right 😆). I've left it as a failsafe since so many edge cases have come up along the way.

Funny, I can't trigger it with fast typing on the alphanumeric mask - only the numerical masks. Makes me think there's probably a solution already sitting in the code that I just need to apply to both scenarios perhaps. I'll look into it more. Good catch!

Another note about this - I noticed it only happens if the input is completely empty before you begin rapidly typing. If there is even 1 valid character before and you type rapidly it does not fall back on the default message. Something that could be improved on but I agree shouldn't be a blocker.

mahoneycm · 2025-01-09T20:55:28Z

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

Polish: I noticed on the first interaction the error message starts at a larger size and then drops to a slightly smaller size. Probably not a blocker but could be nice if we can pin it down!

Kapture.2025-01-09.at.15.53.48.webm

@mahoneycm I am not able to reproduce this, can you confirm it's still an issue after the latest updates?

It's not very common but I'm still able to reproduce after doing a hard refresh on Arc, Chrome, and Safari.

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

…dates

mlloydbixal · 2025-01-13T21:58:44Z

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

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

packages/usa-error-message/src/styles/_usa-error-message.scss Outdated Show resolved Hide resolved

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

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

run prettier

067de74

This comment was marked as outdated.

Sign in to view

mlloydbixal added 2 commits January 9, 2025 12:44

add check for key press combos

8ac4c2a

run prettier/lint

3005b42

mlloydbixal requested a review from mejiaj January 9, 2025 17:51

mlloydbixal added 2 commits January 9, 2025 14:39

update unit test

fcc6317

only create error element once

7672532

mahoneycm requested changes Jan 9, 2025

View reviewed changes

mlloydbixal added 2 commits January 9, 2025 17:21

simulate both key events in unit test

69622bb

fix paste bug, fix cmd + backspace bug

527718c

This comment was marked as outdated.

Sign in to view

mlloydbixal added 7 commits January 10, 2025 16:18

handle shift combo bug, again

f02cc95

remove error message data from jsons

ee666e5

remove error messages from test file

99285df

add comment

f20334f

improvements when using paste

5207a29

add override and default error message for paste

8cc1d86

minor fixes

b1505c0

github-advanced-security bot found potential problems Jan 13, 2025

View reviewed changes

packages/usa-input-mask/src/index.js Fixed Show fixed Hide fixed

mlloydbixal added 4 commits January 13, 2025 14:33

use display properties

d5e195f

fix paste bug

3176a7c

combine error message functionality for hide/show and text content up…

06f4fd8

…dates

add navigational key check

5ca978f

use clipboard api

20a987d

mlloydbixal requested review from mahoneycm and mejiaj January 13, 2025 22:39

mlloydbixal added 2 commits January 13, 2025 20:43

combine debounce functions

541097c

minor grammatical updates, run prettier

ffbf176

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

mlloydbixal commented Nov 20, 2024

mlloydbixal commented Nov 21, 2024

mlloydbixal commented Nov 21, 2024 •

edited

Loading

amycole501 commented Nov 22, 2024

This comment was marked as outdated.

mlloydbixal commented Jan 9, 2025 •

edited

Loading

mahoneycm left a comment

mahoneycm Jan 9, 2025

mlloydbixal Jan 10, 2025

mahoneycm Jan 14, 2025

mlloydbixal Jan 14, 2025

mahoneycm Jan 9, 2025

mlloydbixal Jan 10, 2025 •

edited

Loading

mlloydbixal Jan 10, 2025

mlloydbixal Jan 13, 2025

mahoneycm Jan 9, 2025

mlloydbixal Jan 13, 2025

mahoneycm Jan 14, 2025

This comment was marked as outdated.

mlloydbixal commented Jan 13, 2025

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

mlloydbixal commented Nov 20, 2024

mlloydbixal commented Nov 21, 2024

mlloydbixal commented Nov 21, 2024 • edited Loading

amycole501 commented Nov 22, 2024

This comment was marked as outdated.

mlloydbixal commented Jan 9, 2025 • edited Loading

mahoneycm 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

mlloydbixal Jan 10, 2025 • edited Loading

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

This comment was marked as outdated.

mlloydbixal commented Jan 13, 2025

mlloydbixal commented Nov 13, 2024 •

edited

Loading

mejiaj left a comment •

edited

Loading

mlloydbixal commented Nov 21, 2024 •

edited

Loading

mlloydbixal commented Jan 9, 2025 •

edited

Loading

mlloydbixal Jan 10, 2025 •

edited

Loading