USWDS - Character count: Enhance visual cue when limit is exceeded #5908

mahoneycm · 2024-05-01T21:02:58Z

Summary

Enhanced visual cue when maxlength is exceeded. Now, the visual state of the character count will reflect its validation state.

Breaking change

This is not a breaking change.

Related issue

Closes #5851

Related pull requests

Changelog →

Preview link

Character count →

Problem statement

Testing results show that users expect additional indication that they have exceeded the limit. Additionally, screen magnification users may be unable to see the character count status message beneath the textarea input.

Solution

Add additional visual cues to let users know they have exceeded the character count limit.

Major changes

When users surpass the character limit, the usa-input--error class is added to the form input
- This class will be removed when count is beneath limit
If users are over the character limit and remove focus from the input element, usa-input--error and usa-form-group--error are added to their relevant elements.
- Once the input is beneath the count limit, removing focus will appropriately remove these classes

Testing and review

Character count behaviors

Visit character component story →
For both input variants, surpass relevant character limits.
Confirm input error class and styles are applied correctly
focusout each component
Confirm label and form group error classes and styles are applied correctly
Return to the input and backspace input to validate character count
Confirm input error class and styles are removed
focusouteach component
Confirm label and form group error classes and styles are removed

Testing checklist

npm run test runs without error
usa-input--errorclasses are applied on character input over character limit
usa-input--errorclasses are removed on character input under character limit
usa-form-group--error classes are applied after focusout of over limit input
usa-form-group--error classes are removed after focusout of under limit input
usa-label--error classes are applied after focusout of over limit input
usa-label--error classes are removed after focusout of under limit input
Character count JS matches USWDS code standards.
New unit tests match USWDS code standards

…erCountElements

… focusout

…sts; add no label and no form group templates

mahoneycm

Due to the unit test updates, there are a handful of changed files with this PR. Added some comments to help add clarity to each of the changes:

mahoneycm · 2024-05-02T15:00:40Z

packages/usa-character-count/src/index.js

+  const formGroupEl = characterCountEl.querySelector(FORM_GROUP);
+
+  if (!formGroupEl) {
+    throw new Error(`${CHARACTER_COUNT} is missing inner ${FORM_GROUP}`);
+  }
+
+  const labelEl = characterCountEl.querySelector(LABEL);
+
+  if (!labelEl) {
+    throw new Error(`${CHARACTER_COUNT} is missing inner ${LABEL}`);
+  }
+


Note
Added checks for form group and label elements. These elements are necessary for the overall structure of the component and will result in JS errors for toggleErrorState if they are missing.

mahoneycm · 2024-05-02T15:01:53Z

packages/usa-character-count/src/index.js

+/**
+ * Updates character count form elements to match error status of input.
+ *
+ * @description On focusout, it will update the input label and form group to match the current state of the input element.
+ * Called on focusout instead of input to prevent content shift while typing.
+ * @param {HTMLInputElement|HTMLTextAreaElement} inputEl The character count input element
+ */
+const toggleErrorState = (inputEl) => {
+  const { labelEl, formGroupEl } = getCharacterCountElements(inputEl);
+  const errorState = inputEl.classList.contains(INPUT_ERROR_CLASS);
+
+  labelEl.classList.toggle(LABEL_ERROR_CLASS, errorState);
+  formGroupEl.classList.toggle(FORM_GROUP_ERROR_CLASS, errorState);
+};
+


Note
toggleErrorState adds/removes form-group and usa-label with relevant --error classes. Called on focusout

mahoneycm · 2024-05-02T15:02:58Z

packages/usa-character-count/src/index.js

+const FORM_GROUP_CLASS = `${PREFIX}-form-group`;
+const FORM_GROUP_ERROR_CLASS = `${FORM_GROUP_CLASS}--error`;
+const FORM_GROUP = `.${FORM_GROUP_CLASS}`;
+const LABEL_CLASS = `${PREFIX}-label`;
+const LABEL_ERROR_CLASS = `${LABEL_CLASS}--error`;
+const LABEL = `.${LABEL_CLASS}`;


Note
Added classes and element used by toggleErrorState. Organized by when they appear in markup/DOM

mahoneycm · 2024-05-02T15:03:57Z

packages/usa-character-count/src/index.js

+    FORM_GROUP_ERROR_CLASS,
+    LABEL_ERROR_CLASS,
+    INPUT_ERROR_CLASS,


Note
Exported for use in new unit tests

mahoneycm · 2024-05-02T15:10:04Z

packages/usa-character-count/src/test/character-count.template.html

Updated unit test templates

I added usa-form-group and usa-label's to all character count unit tests for consistency and to prevent JS errors now that the component checks for these elements.

mahoneycm · 2024-05-02T15:11:13Z

packages/usa-character-count/src/test/invalid-template-no-form-group.spec.js

Note
New unit test to check for the existence of form group element

mahoneycm · 2024-05-02T15:11:54Z

packages/usa-character-count/src/test/invalid-template-no-label.spec.js

Note
New unit test to check for the existence of the label element

mahoneycm · 2024-05-02T15:12:40Z

packages/usa-character-count/src/test/character-count.spec.js

+    it("should add form group error classes on focusout when the input has error class", () => {
+      input.classList.add(INPUT_ERROR_CLASS);
+
+      EVENTS.focusout(input);
+
+      assert.strictEqual(
+        formGroup.classList.contains(FORM_GROUP_ERROR_CLASS),
+        true
+      );
+      assert.strictEqual(label.classList.contains(LABEL_ERROR_CLASS), true);
+    });
+
+    it("should remove form group error classes on focusout when the input does not have error class", () => {
+      assert.strictEqual(input.classList.contains(INPUT_ERROR_CLASS), false);
+      formGroup.classList.add(FORM_GROUP_ERROR_CLASS);
+      label.classList.add(LABEL_ERROR_CLASS);
+
+      EVENTS.focusout(input);
+
+      assert.strictEqual(
+        formGroup.classList.contains(FORM_GROUP_ERROR_CLASS),
+        false
+      );
+      assert.strictEqual(label.classList.contains(LABEL_ERROR_CLASS), false);
+    });


Note
New testing requirements to check for the addition / removal of error states on input and focusout

mahoneycm · 2024-05-02T15:14:50Z

packages/usa-character-count/src/index.js

+    focusout: {
+      [INPUT]() {
+        toggleErrorState(this);
+      },
+    },


Add form group error classes on focusout

This idea came from a discussion between @jaclinec and I. We wanted to add the full error state classes but didn't want to have the content shift while the user was typing. She suggested we add these classes only after the user leaves the field.

I think this approach makes sense. One thing I noticed is that it didn't quite reverse the way I expected when when I returned to the input and resolved the error. (See screenshot below).

To replicate:

Turn on the input error state by entering too many characters

Move focus out of the input, which activates the form group error styles

Return focus to the input

Remove enough characters so that it no longer exceeds maxlength

Keep focus on the input and notice it still shows an error state, even though there is no error

@amyleadem this is the intentional behavior based on @jaclinec's recommendation to not cause content shift while the user is typing (see comment above and testing instructions)

If the content shift on removal is acceptable, I can make it so that the error state is immediately removed rather than waiting for focusout.

Here's a quick example of adding/removing the classes on input. I think this would be particularly jarring for screen magnification users

Kapture.2024-05-23.at.10.02.35.webm

mahoneycm · 2024-05-02T15:19:39Z

packages/usa-character-count/src/index.js

@@ -150,9 +169,25 @@ const updateCountMessage = (inputEl) => {
    inputEl.setCustomValidity("");
  }

+  inputEl.classList.toggle(INPUT_ERROR_CLASS, isOverLimit);


Note
Adds / removes input error classes to match invalid status message class

amycole501 · 2024-05-02T18:03:14Z

@mahoneycm we think there might be an issue with the blue focus indicator and the red indicator not having enough contrast with one another. Is there a way to add a small space between the two (maybe a few pixels) to make a distinction there are two states happening (one focus, one error)? https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html

mahoneycm · 2024-05-03T20:11:20Z

@amycole501 Here's what it looks like it with an offset of 2px

Kapture.2024-05-03.at.15.59.41.webm

The input shrinks a bit but this is actually a result of the error border being added and not the outline offset. The same difference in input size occurs with or without the offset.

What do we think about something like this?

This issue might be a bit out of scope for this specific issue but definitely something we should consider with #5884

CC: @jaclinec @mejiaj @amyleadem

amycole501 · 2024-05-06T19:50:49Z

I like it! Would like to know what @alex-hull thinks but the separation makes it much easier to see the two borders.

amyleadem

@mahoneycm
I started testing the interactions on this and generally it looks good! I had one question below about what happens after you fix an error (shown in the comment below). Let me know if you want to discuss!

I'll return to the code review once we figure that out.

amyleadem · 2024-05-22T22:47:12Z

packages/usa-character-count/src/index.js

+    focusout: {
+      [INPUT]() {
+        toggleErrorState(this);
+      },
+    },


I think this approach makes sense. One thing I noticed is that it didn't quite reverse the way I expected when when I returned to the input and resolved the error. (See screenshot below).

To replicate:

Turn on the input error state by entering too many characters

Move focus out of the input, which activates the form group error styles

Return focus to the input

Remove enough characters so that it no longer exceeds maxlength

Keep focus on the input and notice it still shows an error state, even though there is no error

mahoneycm added 10 commits May 1, 2024 11:48

Define additional character count elements and add them to getCharact…

e86636a

…erCountElements

Toggle input error with character count validation

61575f7

Create toggleErrorState function for form group error styles; call on…

badd291

… focusout

Run prettier

e46d232

correctly order character element definitions/checks

db85d06

Export error classes for unit testing

5aed8b4

Unit tests: Add required form group and label elements to all unit te…

a5f6583

…sts; add no label and no form group templates

Unit tests: Add no form group and no label spec files

09dda8a

Add new feature tests to character count spec file

550d53e

Run prettier

fec6353

mahoneycm mentioned this pull request May 2, 2024

USWDS-Site - Changelog: Character count visual cues [#5908] uswds/uswds-site#2648

Open

mahoneycm commented May 2, 2024

View reviewed changes

mahoneycm requested review from mejiaj, amyleadem, jaclinec and amycole501 and removed request for amycole501 May 2, 2024 15:24

mahoneycm marked this pull request as ready for review May 2, 2024 15:24

amyleadem requested changes May 22, 2024

View reviewed changes

mahoneycm requested a review from amyleadem May 23, 2024 14:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS - Character count: Enhance visual cue when limit is exceeded #5908

USWDS - Character count: Enhance visual cue when limit is exceeded #5908

mahoneycm commented May 1, 2024 •

edited

mahoneycm left a comment

mahoneycm May 2, 2024

mahoneycm May 2, 2024

mahoneycm May 2, 2024

mahoneycm May 2, 2024

mahoneycm May 2, 2024

mahoneycm May 2, 2024

mahoneycm May 2, 2024

mahoneycm May 2, 2024

mahoneycm May 2, 2024

amyleadem May 22, 2024 •

edited

mahoneycm May 23, 2024

mahoneycm May 2, 2024

amycole501 commented May 2, 2024

mahoneycm commented May 3, 2024

amycole501 commented May 6, 2024

amyleadem left a comment

amyleadem May 22, 2024 •

edited

USWDS - Character count: Enhance visual cue when limit is exceeded #5908

Are you sure you want to change the base?

USWDS - Character count: Enhance visual cue when limit is exceeded #5908

Conversation

mahoneycm commented May 1, 2024 • edited

Summary

Breaking change

Related issue

Related pull requests

Preview link

Problem statement

Solution

Major changes

Testing and review

Character count behaviors

Testing checklist

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

Updated unit test templates

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

Add form group error classes on focusout

amyleadem May 22, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

amycole501 commented May 2, 2024

mahoneycm commented May 3, 2024

amycole501 commented May 6, 2024

amyleadem left a comment

Choose a reason for hiding this comment

amyleadem May 22, 2024 • edited

Choose a reason for hiding this comment

mahoneycm commented May 1, 2024 •

edited

amyleadem May 22, 2024 •

edited

amyleadem May 22, 2024 •

edited