USWDS - Storybook: Create form error story #5879

mahoneycm · 2024-04-22T18:16:05Z

Summary

Added form input error state showcase and controls to forms pattern. This is a general display for development testing and reference.

There are a few issues we might want to address if we want to normalize form input error states across the design system. I've created #5884 to track the issues.

Note

I've also created this draft PR that includes this work and brings error state stories to each individual component story page.

Note that this work might be slightly out of date with the final error showcase PR found in this PR.

Breaking change

This is not a breaking change.

Related issue

Closes #5839

Preview link

Error Form Elements →

Problem statement

Currently, there is no preview or testing environment for form input error states.

Solution

Create a story to showcase form elements in error states. This new story has a boolean error_state control that developers can use to toggle the error state on and off.

When in error state, the twig file conditionally adds:

usa-form-group & usa-form-group--error classes where needed
- In some cases, a new div is created to wrap form content
usa-label—error and “…has an error” labels
usa-error-message spans to showcase helpful error messages
usa-input--error to form elements with eligible input elements

Major changes

New Form pattern: Error Form Element

Testing and review

Visit Form error state pattern story
Confirm all forms have an error state
- Note that some components such as combo box does not have error styles on their inputs due to initialization bug
Confirm error state elements have the red left border when view is lower than desktop widths
Confirm error state control works and is named appropriately
Inspect component markup and logic based DOM structure

Important

Due to initialization bugs, Combo box, input mask, and Time Picker are broken with the error state. Additional information is available in comments in this thread.

…tion

mahoneycm

Additional information and findings

mahoneycm · 2024-04-24T19:54:42Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

+<div class="usa-form-group {% if error_state %}usa-form-group--error{% endif %}">
+  <fieldset class="usa-fieldset margin-top-2">
+    <legend class="usa-legend {% if error_state %}usa-label--error{% endif %}">Checkbox{% if error_state %} has an error{% endif %}</legend>
+    {% if error_state %}<span class="usa-error-message" role="alert">Helpful error message</span>{% endif %}
+    <div class="usa-checkbox">
+      <input
+        class="usa-checkbox__input usa-input--error"


Combo box loses input error class on init

Warning
Adding the usa-input--error class to the combo box nested select element does not carry the class over to its dynamically placed input element. The class remains on the hidden select element. This is true for time picker's combo box element as well.

For situations like these, it may be best to carry over classes from the placeholder element, similar to how we carry over attributes with Modal

It is possible to add the classes to the input element after the component is initialized and this may be the case for most form error validation but I think it's important to make sure it's able to initialize in this state in the event a form causes the page to refresh.

mahoneycm · 2024-04-24T19:58:05Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

+  {% if error_state %}<div class="usa-form-group usa-form-group--error">{% endif %}
+    <label class="usa-label {% if error_state %}usa-label--error{% endif %}" for="example-input-prefix">Input prefix{% if error_state %} has an error{% endif %}</label>
+    {% if error_state %}<span class="usa-error-message" role="alert">Helpful error message</span>{% endif %}
+    <div class="usa-input-group {% if error_state %}usa-input--error{% endif %}">


Input prefix/suffix input group

Tip
We must put the usa-input--error class on the usa-input-group element in order for the styles to display as expected

mahoneycm · 2024-04-24T20:03:32Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

-  <legend class="usa-legend">Checkbox</legend usa-label>
+<div class="usa-form-group {% if error_state %}usa-form-group--error{% endif %}">
+  <fieldset class="usa-fieldset margin-top-2">
+    <legend class="usa-legend {% if error_state %}usa-label--error{% endif %}">Checkbox{% if error_state %} has an error{% endif %}</legend>


Legend and error labels

Tip
usa-legend and usa-label output the same base styles. Because of this, I was able to safely add the usa-label--error class without any additional changes or unexpected style conflicts.

This seems like an opinionated choice and might cause confusion.

Alternatively we could add the usa-label class as well but this does not introduce any styles that are not already present thanks to usa-legend

Semi-related, we might want to move the duplicate styles from both definitions to a mixin to reduce duplicate code:

uswds/packages/usa-legend/src/styles/_usa-legend.scss

Lines 3 to 13 in 98566ec

.usa-legend {

@include typeset(

$theme-form-font-family,

$theme-body-font-size,

$theme-input-line-height

);

display: block;

font-weight: font-weight("normal");

margin-top: units(3);

max-width: units($theme-input-max-width);

}

uswds/packages/usa-label/src/styles/_usa-label.scss

Lines 3 to 13 in 98566ec

.usa-label {

@include typeset(

$theme-form-font-family,

$theme-body-font-size,

$theme-input-line-height

);

display: block;

font-weight: font-weight("normal");

margin-top: units(3);

max-width: units($theme-input-max-width);

}

I've created #5894 for additional discussion and to track work if we decide to move forward with this refactor

mahoneycm · 2024-04-24T20:06:19Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

 <form class="usa-form">
  <div class="usa-character-count">
-    <div class="usa-form-group">
-      <label class="usa-label" for="with-hint-input">Character count</label>
+    <div class="usa-form-group {% if error_state %}usa-form-group--error{% endif %}">


usa-form and usa-form-group

Note
While we could add the usa-form-group--error class to <form class="usa-form"> elements, I believe we should avoid doing this and only add it to usa-form-group elements.

Setting the error on the form element would add the error class to the entire form and not just the form question that holds the error.

This could be a useful comment in code.

Comment added in 1723270

mahoneycm · 2024-04-24T20:07:21Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

+  {% if error_state %}<div class="usa-form-group usa-form-group--error">{% endif %}
+    <label class="usa-label {% if error_state %}usa-label--error{% endif %}" for="ssn">Input mask{% if error_state %} has an error{% endif %}</label>


Input mask error

Warning
Input mask breaks due to DOM structure changing.

Related to: #5517

Also noting this error is causing the time picker to not initialize properly in the storybook preview

Time picker doesn't initialize because of the new wrapper? Same issue as input mask?

Time picker doesn't initialize because of the JS error caused by input mask. Removing input mask or the usa-form-group wrapper will allow the time picker to initialize correctly.

I added a comment in 1723270 to help outline this issue.

mahoneycm · 2024-04-24T20:25:06Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

 <form class="usa-form">
-  <label class="usa-label" for="example-input-suffix">Input suffix</label>
-  <div class="usa-input-group usa-input-group--sm">
-    <input
-      id="example-input-suffix"
-      class="usa-input"
-      pattern="[0-9]*"
-      inputmode="numeric"
-      {% if disabled_state == 'disabled' %} disabled
-      {% elseif disabled_state == 'aria-disabled' %} aria-disabled="true" {%- endif %}
-    />
-    <div class="usa-input-suffix" aria-hidden="true">lbs.</div>
-  </div>
-</form>
-
-<fieldset class="usa-fieldset">
-  <legend class="usa-legend">Memorable date</legend>
-  <span class="usa-hint" id="mdHint">For example: January 19 2000</span>
-  <div class="usa-memorable-date">
-    <div class="usa-form-group usa-form-group--month usa-form-group--select">
-      <label class="usa-label" for="date_of_birth_month">Month</label>
-      <select
-        class="usa-select"
-        id="date_of_birth_month"
-        name="date_of_birth_month"
-        aria-describedby="mdHint"
-        {% if disabled_state == 'disabled' %} disabled
-        {% elseif disabled_state == 'aria-disabled' %} aria-disabled="true" {%- endif %}
-      >
-        <option value>- Select -</option>
-        <option value="1">01 - January</option>
-        <option value="2">02 - February</option>
-        <option value="3">03 - March</option>
-        <option value="4">04 - April</option>
-        <option value="5">05 - May</option>
-        <option value="6">06 - June</option>
-        <option value="7">07 - July</option>
-        <option value="8">08 - August</option>
-        <option value="9">09 - September</option>
-        <option value="10">10 - October</option>
-        <option value="11">11 - November</option>
-        <option value="12">12 - December</option>
-      </select>
-    </div>
-    <div class="usa-form-group usa-form-group--day">
-      <label class="usa-label" for="date_of_birth_day">Day</label>
+  {% if error_state %}<div class="usa-form-group usa-form-group--error">{% endif %}


Adding usa-form-group divs

Note
In order for the red border to highlight the form input with an error, the elements must be nested within a div with the usa-form-group and usa-form-group--error classes.

We should consider the implications of this while creating guidance for setting error states.

I've used if statements to wrap the opening and closing tags to only add the divs when the error state is active.

packages/usa-form/src/test/test-pattern/test-usa-form.twig

mahoneycm · 2024-04-24T20:30:44Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

-    >Time picker</label
+<div class="usa-form-group {% if error_state %}usa-form-group--error{% endif %}">
+  <label class="usa-label {% if error_state %}usa-label--error{% endif %}" id="appointment-time-label" for="appointment-time"
+    >Time picker{% if error_state %} has an error{% endif %}</label


Time picker error input

Warning
Due to Combo box's dynamic input element not receiving the same classes as it's select placeholder, the error input classes are not set on initialization

mejiaj

The warnings and other notes you've set in this PR are helpful. It'd be nice to add them to the code (preferably if they're linked to an issue) so that it doesn't get lost.

Something for us to keep in mind moving forward, but we should move away from hardcoding component markup as much as possible. This isn't re-usable and can introduce bloat into the codebase.

I understand the intent of this PR is to see the current state of errors in USWDS forms. To accomplish that we should show the most accurate state, based on existing guidance, and not try to improvise fixes or solutions.

Can you add comments in code where necessary and remove any workarounds?

mejiaj · 2024-04-26T13:24:41Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

-    <div class="usa-form-group">
-      <label class="usa-label" for="with-hint-input">Character count</label>
+    <div class="usa-form-group {% if error_state %}usa-form-group--error{% endif %}">
+      <label class="usa-label {% if error_state %}usa-label--error{% endif %}" for="with-hint-input">Character count{% if error_state %} has an error{% endif %}</label>


The spacing for has an error looks inconsistent.

packages/usa-form/src/test/test-pattern/test-usa-form.twig

mejiaj · 2024-04-26T13:31:42Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

+  {% if error_state %}<div class="usa-form-group usa-form-group--error">{% endif %}
+    <label class="usa-label {% if error_state %}usa-label--error{% endif %}" for="ssn">Input mask{% if error_state %} has an error{% endif %}</label>


Time picker doesn't initialize because of the new wrapper? Same issue as input mask?

mejiaj · 2024-04-26T13:37:31Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

 <form class="usa-form">
  <div class="usa-character-count">
-    <div class="usa-form-group">
-      <label class="usa-label" for="with-hint-input">Character count</label>
+    <div class="usa-form-group {% if error_state %}usa-form-group--error{% endif %}">


This could be a useful comment in code.

packages/usa-form/src/test/test-pattern/test-usa-form.twig

mejiaj · 2024-04-26T13:44:31Z

packages/usa-form/src/test/test-pattern/test-usa-form.twig

-  <legend class="usa-legend">Checkbox</legend usa-label>
+<div class="usa-form-group {% if error_state %}usa-form-group--error{% endif %}">
+  <fieldset class="usa-fieldset margin-top-2">
+    <legend class="usa-legend {% if error_state %}usa-label--error{% endif %}">Checkbox{% if error_state %} has an error{% endif %}</legend>


This seems like an opinionated choice and might cause confusion.

mahoneycm · 2024-04-26T16:57:47Z

@mejiaj I've added my GH comments as ~~liquid~~ twig syntax comments on the twig template for more visibility. I've linked #5884 to discuss additional work and improvements needed for a uniform experience across form inputs

mejiaj

Looks good, didn't find any a11y issues with axe devtools either.

mahoneycm added 7 commits April 19, 2024 17:00

Create storybook controls for error state showcase

07cce51

Add conditional error state classes and error messages to form collec…

280994d

…tion

Add error label classes and conditional error label

d26ec09

Add missing form group class to checkbox group

711b6b7

Remove usa-form-group--error class from form and fieldset tags

0c71b42

Normalize error labels for consistency

57732f7

Add usa-input--error class to combobox select

d655689

mahoneycm commented Apr 24, 2024

View reviewed changes

mahoneycm mentioned this pull request Apr 24, 2024

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

Open

3 tasks

mahoneycm requested review from mejiaj and amyleadem April 25, 2024 13:51

mahoneycm marked this pull request as ready for review April 25, 2024 13:53

mejiaj requested changes Apr 26, 2024

View reviewed changes

mahoneycm added 4 commits April 26, 2024 11:27

Remove '...has an error' from labels

dc0cfbc

Added GH comments to code

1723270

Add 'test' to story name

059019b

Add liquid if statement to combobox input class

e11c7af

mahoneycm requested a review from mejiaj April 26, 2024 16:57

mejiaj approved these changes May 2, 2024

View reviewed changes

This was referenced May 6, 2024

USWDS - Input Mask: Fix input mask for nested inputs #5518

Open

USWDS-Site: Documentation updates for 3.8.1 uswds/uswds-site#2654

Draft

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

USWDS - Storybook: Create form error story #5879

USWDS - Storybook: Create form error story #5879

mahoneycm commented Apr 22, 2024 •

edited

mahoneycm left a comment

mahoneycm Apr 24, 2024 •

edited

mahoneycm Apr 24, 2024

mahoneycm Apr 24, 2024

mejiaj Apr 26, 2024

mahoneycm Apr 26, 2024

mahoneycm Apr 24, 2024

mejiaj Apr 26, 2024

mahoneycm Apr 26, 2024

mahoneycm Apr 24, 2024

mahoneycm Apr 24, 2024

mejiaj Apr 26, 2024

mahoneycm Apr 26, 2024

mahoneycm Apr 24, 2024

mahoneycm Apr 24, 2024

mejiaj left a comment

mejiaj Apr 26, 2024

mejiaj Apr 26, 2024

mejiaj Apr 26, 2024

mejiaj Apr 26, 2024

mahoneycm commented Apr 26, 2024 •

edited

mejiaj left a comment

	.usa-legend {
	@include typeset(
	$theme-form-font-family,
	$theme-body-font-size,
	$theme-input-line-height
	);
	display: block;
	font-weight: font-weight("normal");
	margin-top: units(3);
	max-width: units($theme-input-max-width);
	}

	.usa-label {
	@include typeset(
	$theme-form-font-family,
	$theme-body-font-size,
	$theme-input-line-height
	);
	display: block;
	font-weight: font-weight("normal");
	margin-top: units(3);
	max-width: units($theme-input-max-width);
	}

		{% if error_state %}<div class="usa-form-group usa-form-group--error">{% endif %}
		<label class="usa-label {% if error_state %}usa-label--error{% endif %}" for="ssn">Input mask{% if error_state %} has an error{% endif %}</label>

USWDS - Storybook: Create form error story #5879

Are you sure you want to change the base?

USWDS - Storybook: Create form error story #5879

Conversation

mahoneycm commented Apr 22, 2024 • edited

Summary

Breaking change

Related issue

Preview link

Problem statement

Solution

Major changes

Testing and review

mahoneycm left a comment

Choose a reason for hiding this comment

Additional information and findings

mahoneycm Apr 24, 2024 • edited

Choose a reason for hiding this comment

Combo box loses input error class on init

Choose a reason for hiding this comment

Input prefix/suffix input group

Choose a reason for hiding this comment

Legend and error labels

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

usa-form and usa-form-group

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Input mask error

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

Adding usa-form-group divs

Choose a reason for hiding this comment

Time picker error input

mejiaj 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

mahoneycm commented Apr 26, 2024 • edited

mejiaj left a comment

Choose a reason for hiding this comment

mahoneycm commented Apr 22, 2024 •

edited

mahoneycm Apr 24, 2024 •

edited

`usa-form` and `usa-form-group`

Adding `usa-form-group` divs

mahoneycm commented Apr 26, 2024 •

edited