LG-4951: Link relevant help articles in the IAL2 flow

.erb-lint.yml

@@ -9,8 +9,20 @@ linters:
       - '*/app/views/accounts/*'
       - '*/app/views/idv/confirmations/*'
       - '*/app/views/idv/capture_doc/*'
-      - '*/app/views/idv/doc_auth/*'
-      - '*/app/views/idv/phone/*'
+      - '*/app/views/idv/doc_auth/_back.html.erb'
+      - '*/app/views/idv/doc_auth/_error_messages.html.erb'
+      - '*/app/views/idv/doc_auth/_ssn_init.html.erb'
+      - '*/app/views/idv/doc_auth/_ssn_update.html.erb'
+      - '*/app/views/idv/doc_auth/_start_over_or_cancel.html.erb'
+      - '*/app/views/idv/doc_auth/agreement.html.erb'
+      - '*/app/views/idv/doc_auth/document_capture.html.erb'
+      - '*/app/views/idv/doc_auth/link_sent.html.erb'
+      - '*/app/views/idv/doc_auth/no_camera.html.erb'
+      - '*/app/views/idv/doc_auth/upload.html.erb'
+      - '*/app/views/idv/doc_auth/send_link.html.erb'
+      - '*/app/views/idv/doc_auth/verify.html.erb'
+      - '*/app/views/idv/doc_auth/verify_wait.html.erb'
+      - '*/app/views/idv/phone/new.html.erb'
       - '*/app/views/idv/shared/_document_capture.html.erb'
       - '*/app/views/event_disavowal/*'
       - '*/app/views/mfa_confirmation/*'

app/assets/stylesheets/components/_external-link.scss

@@ -12,5 +12,7 @@
   &::after {
     // The icon is displayed inline, which has no implicit height when included in a flex context.
     align-self: stretch;
+    margin-left: units(.5);
+    margin-right: units(2px);
   }
 }

app/javascript/packages/document-capture/components/block-link.jsx

@@ -1,19 +1,31 @@
+import useI18n from '../hooks/use-i18n';
+
 /** @typedef {import('react').ReactNode} ReactNode */
 
 /**
  * @typedef BlockLinkProps
  *
  * @prop {string} url Link destination.
+ * @prop {boolean=} isNewTab Whether link should open in a new tab. Defaults to false. Use best
+ * judgment to reserve new tabs to when absolutely necessary, such as when form data may otherwise
+ * be lost.
  * @prop {ReactNode} children Child elements.
  */
 
 /**
  * @param {BlockLinkProps} props
  */
-function BlockLink({ url, children }) {
+function BlockLink({ url, children, isNewTab = false }) {
+  const { t } = useI18n();
+
+  const classes = ['usa-link', 'block-link', isNewTab && 'usa-link--external']
+    .filter(Boolean)
+    .join(' ');
+
   return (
-    <a href={url} className="usa-link block-link">
+    <a href={url} className={classes} target={isNewTab ? '_blank' : undefined}>
       {children}
+      {isNewTab && <span className="usa-sr-only"> {t('links.new_window')}</span>}
       <svg
         xmlns="http://www.w3.org/2000/svg"
         viewBox="0 0 5.2 8.91"

app/javascript/packages/document-capture/components/documents-step.jsx

@@ -58,7 +58,7 @@ function DocumentsStep({
         {!isMobile && <li>{t('doc_auth.tips.document_capture_id_text4')}</li>}
       </ul>
       {serviceProvider.name && (
-        <BlockLink url={serviceProvider.getFailureToProofURL('documents_having_trouble')}>
+        <BlockLink url={serviceProvider.getFailureToProofURL('documents_having_trouble')} isNewTab>
           {formatHTML(t('doc_auth.info.get_help_at_sp_html', { sp_name: serviceProvider.name }), {
             strong: 'strong',
           })}

app/javascript/packages/document-capture/components/review-issues-step.jsx

@@ -124,7 +124,10 @@ function ReviewIssuesStep({
         </>
       )}
       {serviceProvider.name && (
-        <BlockLink url={serviceProvider.getFailureToProofURL('review_issues_having_trouble')}>
+        <BlockLink
+          url={serviceProvider.getFailureToProofURL('review_issues_having_trouble')}
+          isNewTab
+        >
           {formatHTML(t('doc_auth.info.get_help_at_sp_html', { sp_name: serviceProvider.name }), {
             strong: 'strong',
           })}

app/services/marketing_site.rb

@@ -42,6 +42,30 @@ def self.help_authentication_app_url
     URI.join(BASE_URL, locale_segment, 'help/creating-an-account/authentication-application/').to_s
   end
 
+  def self.help_idv_supported_documents_url
+    URI.join(
+      BASE_URL,
+      locale_segment,
+      'help/verify-your-identity/accepted-state-issued-identification/',
+    ).to_s
+  end
+
+  def self.help_idv_verify_by_mail_url
+    URI.join(
+      BASE_URL,
+      locale_segment,
+      'help/verify-your-identity/verify-your-address-by-mail/',
+    ).to_s
+  end
+
+  def self.help_idv_verify_by_phone_url
+    URI.join(
+      BASE_URL,
+      locale_segment,
+      'help/verify-your-identity/phone-number-and-phone-plan-in-your-name/',
+    ).to_s
+  end
+
   def self.help_which_authentication_method_url
     URI.join(
       BASE_URL,

app/views/idv/doc_auth/welcome.html.erb

@@ -72,30 +72,48 @@
     </li>
   </ul>
 
-  <% if decorated_session.sp_name %>
-    <%= render(
-      'shared/troubleshooting_options',
-      heading_level: :h3,
-      heading: t('idv.troubleshooting.headings.missing_required_items'),
-      options: [
-        {
-          url: idv_doc_auth_return_to_sp_path,
-          text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
-        },
-      ],
-    ) %>
-  <% end %>
+  <%= render(
+        'shared/troubleshooting_options',
+        heading_level: :h3,
+        heading: t('idv.troubleshooting.headings.missing_required_items'),
+        options: [
+          {
+            url: MarketingSite.help_idv_supported_documents_url,
+            text: t('idv.troubleshooting.options.supported_documents'),
+            new_tab: true,
+          },
+          {
+            url: MarketingSite.help_idv_verify_by_phone_url,
+            text: t('idv.troubleshooting.options.learn_more_address_verification_options'),
+            new_tab: true,
+          },
+          decorated_session.sp_name && {
+            url: idv_doc_auth_return_to_sp_path,
+            text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+            new_tab: true,
+          },
+        ].select(&:present?),
+      ) %>
 
   <h2><%= t('doc_auth.instructions.privacy') %></h2>
-  <p><%== t('doc_auth.info.privacy_html', link: new_window_link_to(t('doc_auth.instructions.learn_more'),
-            MarketingSite.security_and_privacy_practices_url)) %></p>
+  <p>
+    <%= t(
+          'doc_auth.info.privacy_html',
+          link: new_window_link_to(
+            t('doc_auth.instructions.learn_more'),
+            MarketingSite.security_and_privacy_practices_url,
+          ),
+        ) %>
+  </p>
 
   <%= validated_form_for :doc_auth,
                          url: url_for,
                          method: 'put',
                          html: { autocomplete: 'off', class: 'margin-top-2 js-consent-continue-form' } do |f| %>
     <br/>
-    <%= f.button :button, t('doc_auth.buttons.continue'), type: :submit,
+    <%= f.button :button,
+                 t('doc_auth.buttons.continue'),
+                 type: :submit,
                  class: 'usa-button--big usa-button--wide' %>
   <% end %>
 

app/views/idv/gpo/index.html.erb

@@ -17,12 +17,24 @@
   <%= t('idv.messages.gpo.timeframe') %>
 </p>
 
-<div class="margin-top-6 margin-bottom-4">
+<div class="margin-top-6 margin-bottom-5">
   <% if @presenter.gpo_mail_bounced? %>
     <%= render 'idv/gpo/new_address', presenter: @presenter %>
   <% else %>
     <%= render 'idv/gpo/address_on_file', presenter: @presenter %>
   <% end %>
 </div>
 
+<%= render(
+      'shared/troubleshooting_options',
+      heading: t('idv.troubleshooting.headings.having_trouble'),
+      options: [
+        {
+          url: MarketingSite.help_idv_verify_by_mail_url,
+          text: t('idv.troubleshooting.options.learn_more_verify_by_mail'),
+          new_tab: true,
+        },
+      ],
+    ) %>
+
 <%= render 'idv/doc_auth/back', fallback_path: @presenter.fallback_back_path %>

app/views/idv/otp_delivery_method/new.html.erb

@@ -48,24 +48,27 @@
         </div>
       </div>
     </label>
-
-    <div class="margin-top-4"></div>
-    <% if gpo_letter_available %>
-      <div class="margin-top-4">
-        <%= t('idv.form.no_alternate_phone_html', link: link_to(t('idv.form.activate_by_mail'), idv_gpo_path)) %>
-      </div>
-    <% end %>
-
-    <div class="margin-top-2">
-      <%= t('instructions.mfa.wrong_number_html', link: link_to(t('forms.two_factor.try_again'), idv_phone_path)) %>
-    </div>
-
   </fieldset>
-  <div class="margin-top-4">
-    <%= submit_tag(t('idv.buttons.send_confirmation_code'), class: 'sm-col-6 col-12 usa-button usa-button--big') %>
+  <div class="margin-y-5">
+    <%= submit_tag(t('idv.buttons.send_confirmation_code'), class: 'usa-button usa-button--big usa-button--wide') %>
   </div>
 <% end %>
 
+<%= render(
+      'shared/troubleshooting_options',
+      heading: t('idv.troubleshooting.headings.having_trouble'),
+      options: [
+        {
+          url: idv_phone_path,
+          text: t('idv.troubleshooting.options.change_phone_number'),
+        },
+        gpo_letter_available && {
+          url: idv_gpo_path,
+          text: t('idv.troubleshooting.options.verify_by_mail'),
+        },
+      ].select(&:present?),
+    ) %>
+
 <div class="margin-top-4 border-top border-primary-light">
   <div class="margin-top-1">
     <%= link_to(t('links.cancel'), idv_cancel_path(step: 'phone_otp_delivery_selection')) %>

app/views/idv/phone/new.html.erb

@@ -61,17 +61,29 @@
  <%= f.input :phone, required: true, input_html: { aria: { invalid: false }, class: 'sm-col-8' }, label: false,
    wrapper_html: { class: 'margin-right-2' } %>
 
-  <% if gpo_letter_available %>
-    <%= render 'idv/phone/verification_options' %>
-  <% end %>
-
-  <%= render 'shared/spinner_button',
-             action_message: t('doc_auth.info.verifying'),
-             class: 'margin-top-4' do %>
-    <%= f.button :submit, t('forms.buttons.continue'), class: 'usa-button--big usa-button--wide' %>
-  <% end %>
+  <div class="margin-y-5">
+    <%= render('shared/spinner_button', action_message: t('doc_auth.info.verifying')) do %>
+      <%= f.button :submit, t('forms.buttons.continue'), class: 'usa-button--big usa-button--wide' %>
+    <% end %>
+  </div>
 <% end %>
 
+<%= render(
+      'shared/troubleshooting_options',
+      heading: t('idv.troubleshooting.headings.having_trouble'),
+      options: [
+        {
+          url: MarketingSite.help_idv_verify_by_phone_url,
+          text: t('idv.troubleshooting.options.learn_more_verify_by_phone'),
+          new_tab: true,
+        },
+        gpo_letter_available && {
+          url: idv_gpo_path,
+          text: t('idv.troubleshooting.options.verify_by_mail'),
+        },
+      ].select(&:present?),
+    ) %>
+
 <div class="margin-top-2 padding-top-1 border-top border-primary-light">
   <%= link_to t('links.cancel'), idv_cancel_path(step: 'phone') %>
 </div>

app/views/idv/phone_errors/_warning.html.erb

@@ -16,9 +16,10 @@ locals:
         local_assigns[:contact_support_option] && {
           url: MarketingSite.contact_url,
           text: t('idv.troubleshooting.options.contact_support', app: APP_NAME),
+          new_tab: true,
         },
         FeatureManagement.enable_gpo_verification? && {
-          text: t('idv.form.activate_by_mail'),
+          text: t('idv.troubleshooting.options.verify_by_mail'),
           url: idv_gpo_path,
         },
         decorated_session.sp_name && {
@@ -27,6 +28,7 @@ locals:
             location: local_assigns.fetch(:name, 'warning'),
           ),
           text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+          new_tab: true,
         },
       ].select(&:present?),
     ) { yield } %>

app/views/idv/phone_errors/failure.html.erb

@@ -3,16 +3,18 @@
       heading: t('idv.failure.phone.heading'),
       options: [
         FeatureManagement.enable_gpo_verification? && {
-          text: t('idv.form.activate_by_mail'),
+          text: t('idv.troubleshooting.options.verify_by_mail'),
           url: idv_gpo_path,
         },
         decorated_session.sp_name && {
           url: return_to_sp_failure_to_proof_path(step: 'phone', location: request.params[:action]),
           text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+          new_tab: true,
         },
         {
           url: MarketingSite.contact_url,
           text: t('idv.troubleshooting.options.contact_support', app: APP_NAME),
+          new_tab: true,
         },
       ].select(&:present?),
     ) do %>

app/views/idv/session_errors/exception.html.erb

@@ -10,13 +10,15 @@
         {
           url: MarketingSite.contact_url,
           text: t('idv.troubleshooting.options.contact_support', app: APP_NAME),
+          new_tab: true,
         },
         decorated_session.sp_name && {
           url: return_to_sp_failure_to_proof_path(
             step: 'verify_info',
             location: request.params[:action],
           ),
           text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+          new_tab: true,
         },
       ].compact,
     ) do %>

app/views/idv/session_errors/failure.html.erb

@@ -8,10 +8,12 @@
             location: request.params[:action],
           ),
           text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+          new_tab: true,
         },
         {
           url: MarketingSite.contact_url,
           text: t('idv.troubleshooting.options.contact_support', app: APP_NAME),
+          new_tab: true,
         },
       ].select(&:present?),
     ) do %>

app/views/idv/session_errors/throttled.html.erb

@@ -10,10 +10,12 @@
             location: request.params[:action],
           ),
           text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+          new_tab: true,
         },
         {
           url: MarketingSite.contact_url,
           text: t('idv.troubleshooting.options.contact_support', app: APP_NAME),
+          new_tab: true,
         },
       ].select(&:present?),
     ) do %>

app/views/idv/session_errors/warning.html.erb

@@ -13,6 +13,7 @@
             location: request.params[:action],
           ),
           text: t('idv.troubleshooting.options.get_help_at_sp', sp_name: decorated_session.sp_name),
+          new_tab: true,
         },
       ].compact,
     ) do %>