[Homepage email signup] Create React widget for homepage email signup form and add new error handling states

[randimays]

Description

On VA.gov at the bottom of the homepage, there is a section titled "Sign up to get the latest VA updates" with an input for an email address.

There is currently no error handling in place for this form. If the form fails to reach the GovDelivery service, the user will be directed to a browser error page (404). There is also no input validation on the form, allowing a user to submit the form with a blank email address or with any combination of characters.

We need to address these gaps in error handling, but we want to avoid adding a lot of Javascript (client-side code) to content-build. Since the form currently lives exclusively in content-build, we need to create a React widget in vets-website for the form and implement it on the homepage in content-build.

Example of an existing vets-website widget:

• Language toggle - vets-website
• Widget implementation (empty div) - content-build

Email signup form, present and future

Existing design (production)

Mobile

Desktop

New design

In #19314, DaveP created the error state for when the GovDelivery service rejects our request or the server response fails for any reason.

Figma: https://www.figma.com/design/60PPoOSpKiXwmNHT01C09J/Home-Page-Updates?node-id=38-3849

Input validation states - desktop and mobile

Server issues - mobile

Server issues - desktop

Summary of the tasks for this ticket

• (content-build) Add a feature toggle to control display of the static HTML form (CB) or a new empty container pointing to a new React widget in vets-website
• (vets-website) Create a React widget for the form to include:
  • Input validation built in from the web component(s)
  • Input validation messaging aligning with the Figma design in New design above
  • Server error handling (pink banner) per the Figma design We do not have access to or control over the GovDelivery server response, so we don't have a use case for this banner now
• Add unit and/or e2e tests for the new React widget as appropriate / capable. Note: React widgets are not able to be tested because the page is split between content-build and vets-website and this creates issues testing in any environment.
• Update monitoring documentation
• Update Datadog homepage synthetic - this has a check for the email input

User story

AS A Veteran or other user when on the VA.gov home page signing up for emailed VA updates
I WANT to know if I make a mistake when entering or submitting my email address
SO THAT I can correct the mistakes and there isn't a 'silent' failure of my signup, thus resulting in my not receiving email updates.

Engineering notes / background / launch plan

It may be helpful to read the technical notes put together as part of the Zero Silent Failures SPIKE for this component: #19242 (comment)

This is a cutover from content-build content to vets-website ticket.

• Create a vets-api Flipper We discussed not needing this feature flipper because the vets-website widget will be looking for a specific container coming from content-build. If it is not there, the widget will not do anything (i.e. there is nothing to flip)
• Create CMS feature toggle, enabled by default
• In content-build: put existing content behind the feature toggle, where enabled = content build content shows, disabled = content-build content does not show.
• Content-build: merge change to keep content-build content visible if CMS toggle is on, wait for prod deploy
• FE: Merge vets-website, wait for prod deploy
• In a Tugboat: test, verify, and document the order of steps to:
  • Run QA test plan and verify state
  • Turn off the content build visibility
  • Turn on the vets-website build visibility
  • Verify new form design

Analytics considerations

// TODO DONE (see below) @FranECross: We currently have a custom event on the submit button for this form. It logs two events:

{
  event: 'cta-button-click',
  'button-type': 'primary',
  'button-click-label': 'Sign up'
}

{
  event: 'homepage-email-sign-up',
  action: 'Homepage email signup'
}

If we choose to use the Design System analytics for this button, we'll get this one event:

{
  type: 'primary',
  label: 'Sign up'
}

@FranECross: The custom event clearly has more detail, but do you want to change anything about it as part of this ticket? OR keep the custom event as-is? Fran: Let's keep the custom event, unchanged. Thanks!

11/1: Fran & Randi discussed whittling this down to a single event instead:

event: 'homepage-email-sign-up'
button-click-label: 'Sign up'

Testing & QA

• @FranECross to help with regression test plan
• At minimum, don't regress ability to signup via GovDelivery form

Roles / assignments

After functional testing, code review, accessibility review, and design review can happen in parallel.

• Functional testing: Chris Kim, Fran Cross (if needed)
• Code review: Chris Kim
• Design review: @davidmpickett
• Accessibility review: @laflannery
• Product acceptance: Fran Cross

Acceptance criteria

ACs should capture expected behavior, to inform test plans. Consider devices, documentation updates including KBs, change management, and content model when applicable.

• Put existing GovDelivery / email signup HTML form on a feature toggle (it should show when the toggle is ON)
• Add an empty container pointing to a new React widget in vets-website (it should show when the toggle is OFF)
• Create a React widget in vets-website for the form to include:
  • Input validation built in from the web component(s)
  • Input validation messaging aligning with the Figma design in New design above
  • Server error handling (pink banner) per the Figma design We do not have access to or control over the GovDelivery server response, so we don't have a use case for this banner now
• Add unit and/or e2e tests for the new React widget as appropriate / capable
• Update Datadog homepage synthetic - this has a check for the email input
• Email form scales appropriately for different browser font sizes
• Create followup ticket for removing feature toggle. [Homepage email signup] Remove CMS feature toggle and related code in content-build #19888
• Accessibility review
• Design review
• Impact analysis is filled out and QA test plan is updated accordingly
• Does this product have an existing regression test plan?
  • Yes, link: https://docs.google.com/spreadsheets/d/1pxzl5N3SDQIbckJnyigU1RbK_qIGMKKCN0ElksuffxM/edit?gid=0#gid=0
  • No, regression test plan will be created by Fran Cross as part of the work / points in this ticket

[FranECross]

@randimays I've answered the analytics question, added names to the roles, and also ticked the box for no current regression test, but indicated that I will create one for this issue. I'll get it done before the work begins.

[jilladams]

Note: @FranECross test plan needs to move to the team Test Plans folder

[FranECross]

Note: @FranECross test plan needs to move to the team Test Plans folder

Moved; thanks for the reminder!

[randimays]

@davidmpickett We also need to warn of a 130 maximum character limit on the email address - I just discovered this in my testing the GovDelivery form. Could you please provide some error text for this scenario?

[FranECross]

@davidmpickett We also need to warn of a 130 maximum character limit on the email address - I just discovered this in my testing the GovDelivery form. Could you please provide some error text for this scenario?

@randimays I've updated the regression plan with a line item for the 130 character limit, and will update with more details after Dave provides error messaging.

[davidmpickett]

So fields with character limits should use the character count variant of the text input component. This displays a live countdown of characters remains and prevents the user from entering more characters than the limit.

[randimays]

@davidmpickett Thanks! That makes this way simpler.

[randimays]

@davidmpickett The Platform utility I'm using to validate the email address universally checks for unacceptable characters and the correct email address format. That means we can't necessarily tell whether an invalid character was entered or if they just didn't finish typing:

Should we generalize that messaging a bit?

[davidmpickett]

@randimays Let's just go with the more general message "Enter a valid email address without spaces using this format: email@domain.com"

[randimays]

Discussed the analytics requirements with Fran, and in the interest of whittling two events down to one, we're going to use this one event when the "Sign up" button is clicked:

event: 'homepage-email-sign-up'
button-click-label: 'Sign up'

Updated the ACs for this as well.

[randimays]

Update: CMS feature toggle (FEATURE_EMAIL_UPDATE_WIDGET) is merged and is ON in both production and staging. I created a Tugboat and the feature toggle is OFF in that environment.

PR for content-build feature toggle & container for the React widget is tested & approved by our team and awaiting Platform review.

The code for the new React widget is complete and has been tested locally. I'm waiting for the content-build PR to be merged so I can test vets-website against content-build's main and validate the feature toggle code in production before merging the widget.

[randimays]

The CI for the content-build code finally passed today (I think it was just luck / Platform folks re-running while I was out). I verified the code working properly in staging and production. The feature toggle is ON and the current/existing form is still functioning as expected in both environments. Next step is for me to re-test the new widget code locally and work on getting that merged.

[randimays]

@davidmpickett @FranECross It turns out we won't be able to handle errors for the service call to GovDelivery. Since we're needing to prefill the email address, we have to structure the service call a specific way that sends the request to them without having access to the response. This means we won't be able to implement the We've run into a problem banner. GovDelivery will handle any service failures on their end / site. We can still do input validation, so all of that error handling / character counting has been added.

Another little issue: the error message we're using for input validation is longer than the web component is designed for. This results in a visual "jump" between the normal width of the form and the extended width due to the length of the error message. Do we want to modify the error message, or file a ticket with DST and release this as-is?

Screen.Recording.2024-11-07.at.7.27.30.AM.mov

[FranECross]

Thanks for this information, @randimays ! I'd like to defer to Dave P for the UX question. Regarding the inability to handle errors for GovDelivery, I feel like that's okay, since it won't be a silent error to the user - they'll just see the errors on the GovDelivery site. @jilladams do you concur?

[randimays]

End-of-sprint update: The widget code (vets-website) is approved by our team and needs a Platform review. Once merged, I will flip the feature toggle off so we can test in staging -- we need a design and accessibility review there. Once approved, we can go to production, flip the feature toggle off there and validate that everything is working as expected. This will definitely carry over.

[randimays]

Update: React widget code was merged a couple hours ago. Prepping a Tugboat for testing for design and a11y. Once that is good to go, we can turn the feature toggle off in production and test there (early next week).

[randimays]

@davidmpickett @laflannery The new email signup widget for the homepage is ready for your review on this Tugboat please: https://web-g1rglcuobmlvgewnhny9uo7f6vigntwi.demo.cms.va.gov/.

Figma designs: https://www.figma.com/design/60PPoOSpKiXwmNHT01C09J/Home-Page-Updates?node-id=38-3849

Note that we don't have access to or control over the GovDelivery API call to send the email address. They'll do any service call failure handling on their end. But - we can require the input and enforce a correct email address before submitting the form.

@FranECross I'm not sure who is supposed to be validating against the test plan for this ticket. I struck out the rows for the pink banner since that wasn't implemented, though. I just noticed that I forgot to disable web component analytics on the button so I need to fix that, but I did add a row to the test plan to validate that as well.

[randimays]

@FranECross Ticket for removing the feature toggle and related code has been created: #19888. It is a little stubby and could use some Product eyes 👀

After this ticket is complete, we can pull in the above ticket when ready.

[laflannery]

@randimays I don't know where the PR for this is so I'm putting my comments here instead:

1. The gray hint text (rgb(113, 118, 122) against the blue background #e1f3f8 does not pass contract requirements. It's only 4.02:1
   
   • I'm also noticing that in the Figma we don't have the character counter - was this a later addition?
2. Focus management: when the error appears, the next tab stop should be the input.
   • We do this on PACT and DUW and it's easier because the error doesn't appear on blur.
   • If you force focus to the error message, this should solve the issue

[randimays]

@davidmpickett we have a contrast issue with the character counter text against the blue background. See Laura's comment above. Do you have a preferred darker color to change this text to?

@laflannery The character counter was decided on in the comments of this ticket here. I'll work on a fix for the focus issue.

[laflannery]

@randimays I looked at the design system color palette and there weren't a ton of gray options that worked but I did find one vads-color-base-dark. That's a ratio of 5.9:1. Are you able to change the counter to this?

[randimays]

@laflannery Yes, I'll do that!

[randimays]

@laflannery @davidmpickett The email signup widget is ready for accessibility and design review again (with the focus and character count color changes). Here's the Tugboat: https://web-fdqyu1aesd2l5ncnirpjdlgsveasozss.demo.cms.va.gov/

There is no corresponding PR for this - all the code has to be merged to main and then combined with a CMS flag in order for this to work, thus a Tugboat!

[laflannery]

Color contrast looks good! Focus is also good! FYI My Mac updated yesterday so I'm on 15.1.1 now and I did hear the error when I tabbed into the field. On NVDA the error was announced immediately

[randimays]

Design approved the widget in Tugboat. New email widget is live in production. Email synthetic has been updated with the new selector in Datadog. Closing as complete.