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 component uses standard USWDS error styles to visually enhance the error state.

Breaking change

This is not a breaking change.

Related issue

Closes #5851

Related pull requests

Changelog →

Preview link

New visual change only

This link contains only the changes from this PR
Character count →

Combined with additional styles

This preview combines this work with #5999. This is what the change will look like on release.
Character count preview with enhanced form group error styles →

Link to demo branch

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 relevant error classes are added to the form input, group, and label elements
This class will be removed when the character count is beneath the limit

Testing and review

Character count behaviors

Visit the demo branch preview →.
For both input variants, surpass relevant character limits.
Confirm label, input, and form group error classes and styles are applied correctly.
Backspace input to validate character count.
Confirm error class and styles are removed.
Run unit test and confirm there are no errors.

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 on character input over character limit
usa-form-group--error classes are removed on character input under character limit
usa-label--error classes are applied on character input over character limit
usa-label--error classes are removed on character input under character limit
Character count JS matches USWDS code standards.
~~Unit tests match USWDS code standards~~ // Unit tests removed

…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.

Removed errors in fe42118

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

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 elements used to add error states. 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

todo: Remove unit test if we remove related errors

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

todo: Remove unit test if we remove related errors

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

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

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.

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

mahoneycm · 2024-07-01T20:08:02Z

@amycole501 Here's what it looks like it with an offset of 2px
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

Currently, I'm leaning towards holding off on implementing this change since it has wider implications than just character count. I think it's a great candidate for #5884 which aims to normalize error states across all form components. I added a checklist item to that issue 👍

mahoneycm · 2024-08-23T16:22:30Z

Update 8/23

Restored group error state on input
Removed focusout behaviors
Created demo branch to showcase changes with updated form group styles from USWDS - Forms: Enhance form group error border in desktop widths #5999

jaclinec

This looks great! Nice work!

amyleadem

@mahoneycm Behavior and styles are looking good @mahoneycm!

I had one open question about the failure of the component when either .usa-label or .usa-form-group is missing. It feels a bit fragile to me. I'm wondering if we should at least mark it as a (potentially) breaking change so that users check that their implementations of the character count component have all the needed elements to work.

Curious what others think!

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

mahoneycm · 2024-09-19T20:12:07Z

How do we feel about the necessity for labels or form group elements?

Seems valid. Feels a little odd to check for valid form HTML, but it matches other patterns where we throw errors if the required component markup is missing.

My opinion
I'd prefer to rely on guidance, but I can also see a case for throwing an error.

This makes sense to me! I went ahead and removed the related error messages and unit tests! We can rely on guidance and example code for proper markup 👍

mejiaj

Confirming that this work displays the character count error state when markup is correct and user goes over limit.

Unit tests and builds pass. No console errors when interacting with the component.

character-count-5908-2024-09-24.at.11.00.41.webm

mejiaj · 2024-09-24T16:11:32Z

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

+// Disabling a11y tests from `npm run test:a11y` because we're demo'ing the failure intentionally.
+export const TestNoLabel = TestNoLabelTemplate.bind({});
+TestNoLabel.parameters = {
+  axe: {
+    mode: "off",
+  },
+};


Tip
This test intentionally fails a11y CI test to view the error state when markup is incorrect/missing.

Followed this guidance to disable a11y tests for those templates. ¹

Footnotes

https://github.com/chanzuckerberg/axe-storybook-testing?tab=readme-ov-file#disabledrules ↩

amyleadem

Looks good to me! Confirmed that the updated styles have appropriate enhancements that make the error state more visible and consistent with other USWDS styles

Screenshots:

thisisdano

LGTM. Passing it over to @heymatthenry for his take.

heymatthenry

LGTM! And a great PR, to boot—clear and thoughtful.

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

Merged

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 suggested changes May 22, 2024

View reviewed changes

packages/usa-character-count/src/index.js Outdated Show resolved Hide resolved

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

mahoneycm mentioned this pull request Jul 1, 2024

USWDS - Enhancement: Normalize form input error states. #5884

Open

8 tasks

mahoneycm added 2 commits August 23, 2024 11:44

Add form group error state on input instead of focus out

b7fa1f0

Update unit tests; run prettier

4cbc41c

mahoneycm mentioned this pull request Aug 23, 2024

Demo repo for #5908 #6036

Closed

Remove toggleErrorState function

95a33e3

This comment was marked as resolved.

Sign in to view

This comment was marked as outdated.

Sign in to view

jaclinec approved these changes Aug 27, 2024

View reviewed changes

mahoneycm mentioned this pull request Aug 28, 2024

USWDS - Forms: Enhance form group error border in desktop widths #5999

Closed

amyleadem reviewed Sep 4, 2024

View reviewed changes

packages/usa-character-count/src/index.js Outdated Show resolved Hide resolved

This comment was marked as outdated.

Sign in to view

mahoneycm added 2 commits September 12, 2024 12:35

Remove label and form group errors

fe42118

Add no label && no form group test stories

84f24b1

This comment was marked as outdated.

Sign in to view

mahoneycm requested review from mejiaj and amyleadem September 12, 2024 19:25

This comment was marked as outdated.

Sign in to view

mahoneycm mentioned this pull request Sep 18, 2024

USWDS-Site: Documentation updates for 3.9.0 uswds/uswds-site#2812

Merged

3 tasks

mahoneycm added 2 commits September 19, 2024 16:07

Remove no label + no form group unit tests

20372c1

Add curly brackets to if statements; Add input ID to js doc @returns

1fc6509

James Mejia added 2 commits September 23, 2024 15:35

Disable a11y test on test templates

96a457c

Run prettier

4c98433

mejiaj self-requested a review September 23, 2024 21:08

mejiaj approved these changes Sep 24, 2024

View reviewed changes

mejiaj reviewed Sep 24, 2024

View reviewed changes

amyleadem approved these changes Sep 25, 2024

View reviewed changes

amyleadem requested review from heymatthenry and thisisdano September 25, 2024 22:29

thisisdano approved these changes Oct 3, 2024

View reviewed changes

heymatthenry approved these changes Oct 4, 2024

View reviewed changes

heymatthenry merged commit ddc28d9 into develop Oct 4, 2024
5 checks passed

heymatthenry deleted the cm-char-count-error-state branch October 4, 2024 18:07

thisisdano mentioned this pull request Oct 4, 2024

USWDS 3.9.0 #6096

Merged

aduth mentioned this pull request Oct 7, 2024

@uswds/uswds: Update types for v3.9.0 (CharacterCount) DefinitelyTyped/DefinitelyTyped#70819

Merged

8 tasks

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

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

Uh oh!

Conversation

mahoneycm commented May 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Breaking change

Related issue

Related pull requests

Preview link

New visual change only

Combined with additional styles

Problem statement

Solution

Major changes

Testing and review

Character count behaviors

Testing checklist

Uh oh!

mahoneycm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mahoneycm May 2, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Updated unit test templates

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amycole501 commented May 2, 2024

Uh oh!

mahoneycm commented May 3, 2024

Uh oh!

amycole501 commented May 6, 2024

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mahoneycm commented Jul 1, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mahoneycm commented Aug 23, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Update 8/23

Uh oh!

This comment was marked as resolved.

This comment was marked as outdated.

Uh oh!

jaclinec left a comment

Choose a reason for hiding this comment

Uh oh!

amyleadem left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

This comment was marked as outdated.

This comment was marked as outdated.

This comment was marked as outdated.

Uh oh!

mahoneycm commented May 1, 2024 •

edited

Loading

mahoneycm May 2, 2024 •

edited

Loading

mahoneycm commented Jul 1, 2024 •

edited

Loading

mahoneycm commented Aug 23, 2024 •

edited

Loading

mejiaj left a comment •

edited

Loading

mejiaj Sep 24, 2024 •

edited

Loading