Review error states recommendations and feasibility for VBA content types

[xiongjaneg]

User Story or Problem Statement

As a Drupal editor, I want to know when I'm making an error or missing a requirement as I'm making edits.

In #16068, Jordan added error states to the Figma design. This ticket is to implement the recommended error states in the design.

Acceptance Criteria

• Design is reviewed for error states (Jordan is consulted as needed).
  • Phone field says "Enter a phone number using the format 123-456-7890" This will likely need to be custom validation because the phone number field supports many formats.
  • Email field says "Enter an email address using the format [email protected]"
    • Validate that an email is entered. It doesn't not have to be va.gov
• "Error message when required fields are empty" matches design. Required fields use Drupal Core and HTML5 so staying away from modifying required fields at this time.
• "Error message for link/URL fields" matches design. This no longer appears in the design.
• If actionable, tickets are stubbed.

[mmiddaugh]

From UX sync:
Default error states for required fields are handled by Drupal Core/HTML 5/server side browser + UI/UX of the messages can be determined by the client side browser = we do not have very much control over these

[mmiddaugh]

Suggestions/questions

• VBA Banners > Banner alert > "Dismissible by user": suggest adding a reminder that dismissible banners are recommended only in non-emergency situations
• VBA Facility > Prepare for your visit > Accordion headers: suggest adding "This header should use sentence case" (similar to the title guidance for Spotlight content)
• VBA Facility Service > Service details > Service locations: Suggest more meaningful help text for "Add service location" button (also present in VA Service Regions)
• Service Location paragraph type > Hours > Additional hours options: Rather than "brief explanation of services offered outside of facility hours" suggest guidance to make it more clear that the field should be used for information relevant to hours of operation or availability
• Service Region > Primary facility > VBA facilities in this region: I don't think it is possible to enter an invalid VBA facility since the field uses typeahead functionality to suggest a list of possible matches.(Same field is present in Service Region >VBA facilities in this region)

Related screenshots

[mmiddaugh]

@davidmpickett does a Service region require at least one associated VBA facility?
If so, we'll want to indicate that the "VBA facilities in this region" field field is required.

[davidmpickett]

@davidmpickett does a Service region require at least one associated VBA facility? If so, we'll want to indicate that the "VBA facilities in this region" field field is required.

This field is intentionally not set to required. There is a use case for Service Regions being saved without any facilities attached to them. Could be during initial set-up, or in preparation before a timed launch. Also because we don't delete content, they would need to be saved in Archive even after all the connections to facilities are severed. These are not the primary use cases, but they are legitimate.

Back in May/June 2023 when we discussed the content specs with the CMS Platform team one of the principles that we establishes was that we shouldn't be overly restrictive with required fields. Basically, fields should only be required if the entity cannot function without them.

We also have a lot of fields that were marked as required "No -> Yes" meaning that we will have them not required during pilot phase and might lock them during/after national rollout

cc @aklausmeier because this is a good content modelling principle to know

[davidmpickett]

• VBA Facility Service > Service details > Service locations: Suggest more meaningful help text for "Add service location" button (also present in VA Service Regions)

There is a defect preventing us from changing this text.

• Service Region > Primary facility > VBA facilities in this region: I don't think it is possible to enter an invalid VBA facility since the field uses typeahead functionality to suggest a list of possible matches.(Same field is present in Service Region >VBA facilities in this region)

It is possible to enter random text here. This error message is for the instance where the user has entered some text, but not selected something from the dropdown.

[davidmpickett]

• VBA Banners > Banner alert > "Dismissible by user": suggest adding a reminder that dismissible banners are recommended only in non-emergency situations

This type of nuanced guidance is best kept to Knowledge Base articles rather than the interface. Since the Design System recommends that banners should be dismissible by default, we also typically word this guidance in the opposite direction:
"Except for emergency alerts, we strongly encourage you to make your banners dismissible." - source
"For emergency situations, you wouldn't want the alert to be dismissable." - source

[aklausmeier]

@thejordanwood comments added to Figma file since we have until end of March to migrate this from CMS to VA Figma space

[swirtSJW]

I'd like to get more specific in the ACs than "Matches Design" only because some what had been in the design are challenging to implement because of the need to patch core and contrib modules.

[xiongjaneg]

Because we have limited time in pre-refinement, I'll pull out annotations from the design and put them in the ACs. EDIT: You did it already, thank you!

[xiongjaneg]

From Steve: how hard did we want to make the validations? Particularly for email?

From Dave: We don't want validation that email is va.gov particularly. This is more of an engineering spike/review about predetermined error messages versus ones we can update.

Jordan did work based on feedback on what is desired, though there may be limitations that don't allow us to follow that feedback. We need to determine the feasibility of the feedback.

[xiongjaneg]

For phone numbers: Do phone numbers need format validation?

From Michelle: We need to accommodate international numbers.

[xiongjaneg]

From Michelle: Are there things we can do to fix the issues for the editors, like parentheses are evil, where we can help the editor.

[xiongjaneg]

From Christian: The intent of the error states feedback response was to capture in the design what the current error states are. That helps to identify and fill gaps in error states.

[davidmpickett]

@davidmpickett to take a pass at reviewing error messages and identifying any VBA specific error messages

[xiongjaneg]

This ticket should capture existing standard error states and what would be new. It should also consider impact on other products.

[mmiddaugh]

See also this comment regarding meaningful help text for Local spotlights

[jilladams]

From planning: Dave noted the next work here is for him to Drupalize the design proposal from Jordan.

[omahane]

@jilladams Steve's question about how hard we want to lock down phone validation is not fully answered. Does someone have some guidance on this?

For example, these numbers are currently in the Facilities API:

210-949-3981 x2
800-451-5796, ext. 3215
970-593-3300 ext. 2805
1-877-469-5300
254-743-2867option3
855-864-0516press2thenpress5

I'll admit, some of these are a little bananas (and suggest that we need more guidance), but we need some more specific validation expectation before this can be worked (or pointed).

[omahane]

Per @davidmpickett, the relevant precursory ticket appears to block this one: #15691

[jilladams]

Noting: Laura did us an audit in #17814. As a result, she's gonna draft / share some proposed guidance with the CMS team. That might resolve #15691 as a no-op, or might not and this ticket might still be blocked by Figuring Things Out.

I've asked Laura to follow up on that ticket once she talks to CMS.

[Agile6MSkinner]

@laflannery @jilladams @davidmpickett @omahane I've seen action on phone number validation that would imply that this has all been working out per Jill's comment on 18-Apr. Are error state recommendations and feasibility sufficiently reviewed? Can we close this?

[davidmpickett]

Basic validation and error states are in place for VBA. All the fields Jordan indicated that should have error messages have some error messaging. Exact wording may differ, but that is also not entirely in our control due to the various sources of error messages.

A note for the future - because of the nested nature of Drupal fields, it is best to evaluate this error and validation at a component level rather than at a product level. Laura's phone number epic is a good example of this.

TL;DR - This ticket can be closed. We have spent multiple cycles on this and some of this is not totally in our control.