LG-5213: IAL2 document capture tips prior to submission

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

@@ -1,7 +1,7 @@
 import { render } from '@testing-library/react';
-import BlockLink from '@18f/identity-document-capture/components/block-link';
+import BlockLink from './block-link';
 
-describe('document-capture/components/block-link', () => {
+describe('BlockLink', () => {
   const linkText = 'link text';
   const url = '/example';
 

app/javascript/packages/components/index.js

@@ -1,2 +1,4 @@
 export { default as Alert } from './alert';
+export { default as BlockLink } from './block-link';
 export { default as Icon } from './icon';
+export { default as TroubleshootingOptions } from './troubleshooting-options';

app/javascript/packages/components/troubleshooting-options.jsx

@@ -0,0 +1,38 @@
+import { BlockLink } from '@18f/identity-components';
+
+/**
+ * @typedef TroubleshootingOption
+ *
+ * @prop {string} url
+ * @prop {string|JSX.Element} text
+ * @prop {boolean=} isExternal
+ */
+
+/**
+ * @typedef TroubleshootingOptionsProps
+ *
+ * @prop {string} heading
+ * @prop {TroubleshootingOption[]} options
+ */
+
+/**
+ * @param {TroubleshootingOptionsProps} props
+ */
+function TroubleshootingOptions({ heading, options }) {
+  return (
+    <section className="troubleshooting-options">
+      <h2>{heading}</h2>
+      <ul className="troubleshooting-options__options">
+        {options.map(({ url, text, isExternal }) => (
+          <li key={url}>
+            <BlockLink url={url} isNewTab={isExternal}>
+              {text}
+            </BlockLink>
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+export default TroubleshootingOptions;

app/javascript/packages/components/troubleshooting-options.spec.jsx

@@ -0,0 +1,34 @@
+import { render } from '@testing-library/react';
+import TroubleshootingOptions from './troubleshooting-options';
+
+describe('TroubleshootingOptions', () => {
+  it('renders a given heading', () => {
+    const { getByRole } = render(<TroubleshootingOptions heading="Need help?" options={[]} />);
+
+    const heading = getByRole('heading');
+
+    expect(heading.textContent).to.equal('Need help?');
+  });
+
+  it('renders given options', () => {
+    const { getAllByRole } = render(
+      <TroubleshootingOptions
+        heading=""
+        options={[
+          { text: <>Option 1</>, url: 'https://example.com/1', isExternal: true },
+          { text: 'Option 2', url: 'https://example.com/2' },
+        ]}
+      />,
+    );
+
+    const links = /** @type {HTMLAnchorElement[]} */ (getAllByRole('link'));
+
+    expect(links).to.have.lengthOf(2);
+    expect(links[0].textContent).to.equal('Option 1 links.new_window');
+    expect(links[0].href).to.equal('https://example.com/1');
+    expect(links[0].target).to.equal('_blank');
+    expect(links[1].textContent).to.equal('Option 2');
+    expect(links[1].href).to.equal('https://example.com/2');
+    expect(links[1].target).to.be.empty();
+  });
+});

app/javascript/packages/document-capture/components/acuant-capture.jsx

@@ -10,6 +10,7 @@ import {
 import { useI18n } from '@18f/identity-react-i18n';
 import AnalyticsContext from '../context/analytics';
 import AcuantContext from '../context/acuant';
+import FailedCaptureAttemptsContext from '../context/failed-capture-attempts';
 import AcuantCaptureCanvas from './acuant-capture-canvas';
 import FileInput from './file-input';
 import FullScreen from './full-screen';
@@ -272,6 +273,9 @@ function AcuantCapture(
   const { isMobile } = useContext(DeviceContext);
   const { t, formatHTML } = useI18n();
   const [attempt, incrementAttempt] = useCounter(1);
+  const { onFailedCaptureAttempt, onResetFailedCaptureAttempts } = useContext(
+    FailedCaptureAttemptsContext,
+  );
   const hasCapture = !isError && (isReady ? isCameraSupported : isMobile);
   useEffect(() => {
     // If capture had started before Acuant was ready, stop capture if readiness reveals that no
@@ -297,7 +301,7 @@ function AcuantCapture(
   /**
    * Returns an analytics payload, decorated with common values.
    *
-   * @template P
+   * @template {ImageAnalyticsPayload|AcuantImageAnalyticsPayload} P
    *
    * @param {P} payload
    *
@@ -480,6 +484,9 @@ function AcuantCapture(
 
     if (assessment === 'success') {
       onChangeAndResetError(data, analyticsPayload);
+      onResetFailedCaptureAttempts();
+    } else {
+      onFailedCaptureAttempt({ isAssessedAsGlare, isAssessedAsBlurry });
     }
 
     setIsCapturingEnvironment(false);

app/javascript/packages/document-capture/components/capture-advice.jsx

@@ -0,0 +1,90 @@
+import { useContext } from 'react';
+import { useI18n } from '@18f/identity-react-i18n';
+import ServiceProviderContext from '../context/service-provider';
+import MarketingSiteContext from '../context/marketing-site';
+import useAsset from '../hooks/use-asset';
+import Warning from './warning';
+
+/** @typedef {import('@18f/identity-components/troubleshooting-options').TroubleshootingOption} TroubleshootingOption */
+
+/**
+ * @typedef CaptureAdviceProps
+ *
+ * @prop {() => void} onTryAgain
+ * @prop {boolean} isAssessedAsGlare
+ * @prop {boolean} isAssessedAsBlurry
+ */
+
+/**
+ * @param {CaptureAdviceProps} props
+ */
+function CaptureAdvice({ onTryAgain, isAssessedAsGlare, isAssessedAsBlurry }) {
+  const { name: spName, getFailureToProofURL } = useContext(ServiceProviderContext);
+  const { documentCaptureTipsURL } = useContext(MarketingSiteContext);
+  const { getAssetPath } = useAsset();
+  const { t } = useI18n();
+
+  return (
+    <Warning
+      heading={t('doc_auth.headings.capture_troubleshooting_tips')}
+      autoFocus
+      actionText={t('idv.failure.button.warning')}
+      actionOnClick={onTryAgain}
+      troubleshootingHeading={t('idv.troubleshooting.headings.still_having_trouble')}
+      troubleshootingOptions={
+        /** @type {TroubleshootingOption[]} */ ([
+          {
+            url: documentCaptureTipsURL,
+            text: t('idv.troubleshooting.options.doc_capture_tips'),
+            isExternal: true,
+          },
+          spName && {
+            url: getFailureToProofURL('capture_tips'),
+            text: t('idv.troubleshooting.options.get_help_at_sp', { sp_name: spName }),
+            isExternal: true,
+          },
+        ].filter(Boolean))
+      }
+    >
+      <p>
+        {isAssessedAsGlare && t('doc_auth.tips.capture_troubleshooting_glare')}
+        {isAssessedAsBlurry && t('doc_auth.tips.capture_troubleshooting_blurry')}{' '}
+        {t('doc_auth.tips.capture_troubleshooting_lead')}
+      </p>
+      <ul className="add-list-reset margin-y-3">
+        <li className="clearfix margin-bottom-3">
+          <img
+            width="82"
+            height="82"
+            src={getAssetPath('idv/capture-tips-surface.svg')}
+            alt={t('doc_auth.tips.capture_troubleshooting_surface_image')}
+            className="float-left margin-right-2"
+          />
+          {t('doc_auth.tips.capture_troubleshooting_surface')}
+        </li>
+        <li className="clearfix margin-bottom-3">
+          <img
+            width="82"
+            height="82"
+            src={getAssetPath('idv/capture-tips-lighting.svg')}
+            alt={t('doc_auth.tips.capture_troubleshooting_lighting_image')}
+            className="float-left margin-right-2"
+          />
+          {t('doc_auth.tips.capture_troubleshooting_lighting')}
+        </li>
+        <li className="clearfix">
+          <img
+            width="82"
+            height="82"
+            src={getAssetPath('idv/capture-tips-clean.svg')}
+            alt={t('doc_auth.tips.capture_troubleshooting_clean_image')}
+            className="float-left margin-right-2"
+          />
+          {t('doc_auth.tips.capture_troubleshooting_clean')}
+        </li>
+      </ul>
+    </Warning>
+  );
+}
+
+export default CaptureAdvice;

app/javascript/packages/document-capture/components/capture-troubleshooting.jsx

@@ -0,0 +1,34 @@
+import { useContext, useState } from 'react';
+import FailedCaptureAttemptsContext from '../context/failed-capture-attempts';
+import CaptureAdvice from './capture-advice';
+
+/** @typedef {import('react').ReactNode} ReactNode */
+
+/**
+ * @typedef CaptureTroubleshootingProps
+ *
+ * @prop {ReactNode} children
+ */
+
+/**
+ * @param {CaptureTroubleshootingProps} props
+ */
+function CaptureTroubleshooting({ children }) {
+  const [didShowTroubleshooting, setDidShowTroubleshooting] = useState(false);
+  const { failedCaptureAttempts, maxFailedAttemptsBeforeTips, lastAttemptMetadata } = useContext(
+    FailedCaptureAttemptsContext,
+  );
+  const { isAssessedAsGlare, isAssessedAsBlurry } = lastAttemptMetadata;
+
+  return failedCaptureAttempts >= maxFailedAttemptsBeforeTips && !didShowTroubleshooting ? (
+    <CaptureAdvice
+      onTryAgain={() => setDidShowTroubleshooting(true)}
+      isAssessedAsGlare={isAssessedAsGlare}
+      isAssessedAsBlurry={isAssessedAsBlurry}
+    />
+  ) : (
+    <>{children}</>
+  );
+}
+
+export default CaptureTroubleshooting;