fix(clerk-js): Improve UX when adding adding phone MFA

.changeset/big-tables-watch.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Improve UX when adding a new phone number as an MFA option

packages/clerk-js/src/ui/components/UserProfile/MfaPhoneCodeScreen.tsx

@@ -18,7 +18,8 @@ import {
 import { Plus } from '../../icons';
 import { getCountryFromPhoneString, handleError, stringToFormattedPhoneString } from '../../utils';
 import { MfaBackupCodeList } from './MfaBackupCodeList';
-import { AddPhone, VerifyPhone } from './PhoneForm';
+import { AddPhone } from './PhoneForm';
+import { VerifyWithCode } from './VerifyWithCode';
 
 type MfaPhoneCodeScreenProps = FormProps;
 export const MfaPhoneCodeScreen = withCardStateProvider((props: MfaPhoneCodeScreenProps) => {
@@ -37,10 +38,10 @@ export const MfaPhoneCodeScreen = withCardStateProvider((props: MfaPhoneCodeScre
         onUseExistingNumberClick={() => wizard.goToStep(2)}
         onReset={onReset}
       />
-      <VerifyPhone
+      <MFAVerifyPhone
         title={localizationKeys('userProfile.mfaPhoneCodePage.title')}
         resourceRef={ref}
-        onSuccess={wizard.nextStep}
+        onSuccess={() => (isInstanceWithBackupCodes ? wizard.goToStep(3) : onSuccess)}
         onReset={() => wizard.goToStep(2)}
       />
       <AddMfa
@@ -57,10 +58,14 @@ export const MfaPhoneCodeScreen = withCardStateProvider((props: MfaPhoneCodeScre
       {isInstanceWithBackupCodes && (
         <SuccessPage
           title={localizationKeys('userProfile.mfaPhoneCodePage.successTitle')}
-          text={[
-            localizationKeys('userProfile.mfaPhoneCodePage.successMessage1'),
-            localizationKeys('userProfile.mfaPhoneCodePage.successMessage2'),
-          ]}
+          text={
+            ref.current?.backupCodes && ref.current?.backupCodes.length > 0
+              ? [
+                  localizationKeys('userProfile.mfaPhoneCodePage.successMessage1'),
+                  localizationKeys('userProfile.mfaPhoneCodePage.successMessage2'),
+                ]
+              : [localizationKeys('userProfile.mfaPhoneCodePage.successMessage1')]
+          }
           onFinish={onReset}
           contents={<MfaBackupCodeList backupCodes={ref.current?.backupCodes} />}
         />
@@ -120,6 +125,50 @@ const EnableMFAButtonForPhone = (
   );
 };
 
+type MFAVerifyPhoneProps = FormProps & {
+  title: LocalizationKey;
+  resourceRef: React.MutableRefObject<PhoneNumberResource | undefined>;
+};
+
+export const MFAVerifyPhone = (props: MFAVerifyPhoneProps) => {
+  const { title, onSuccess, resourceRef, onReset } = props;
+  const card = useCardState();
+  const phone = resourceRef.current;
+  const [setReservedForSecondFactor] = useReverification(() => phone?.setReservedForSecondFactor({ reserved: true }));
+
+  const enableMfa = async () => {
+    card.setLoading(phone?.id);
+    try {
+      await setReservedForSecondFactor();
+      resourceRef.current = phone;
+      onSuccess();
+    } catch (err) {
+      handleError(err, [], card.setError);
+    } finally {
+      card.setIdle();
+    }
+  };
+
+  return (
+    <FormContainer
+      headerTitle={title}
+      headerSubtitle={localizationKeys('userProfile.phoneNumberPage.verifySubtitle', {
+        identifier: resourceRef.current?.phoneNumber,
+      })}
+    >
+      <VerifyWithCode
+        nextStep={() => {
+          void enableMfa();
+        }}
+        identification={resourceRef.current}
+        identifier={resourceRef.current?.phoneNumber}
+        prepareVerification={resourceRef.current?.prepareVerification}
+        onReset={onReset}
+      />
+    </FormContainer>
+  );
+};
+
 const AddMfa = (props: AddMfaProps) => {
   const { onSuccess, onReset, title, onAddPhoneClick, onUnverifiedPhoneClick, resourceRef } = props;
   const { user } = useUser();

packages/clerk-js/src/ui/components/UserProfile/__tests__/MfaPage.test.tsx

@@ -104,7 +104,14 @@ describe('MfaPage', () => {
     });
 
     it('Complete verification with phone_code and autogenerated backup codes', async () => {
-      const { wrapper, fixtures } = await createFixtures(initConfig);
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withPhoneNumber({ second_factors: ['phone_code'], used_for_second_factor: true });
+        f.withUser({
+          phone_numbers: [{ phone_number: '+306911111111', id: 'id', backup_codes: ['111111', '111111'] }],
+          two_factor_enabled: true,
+        });
+        f.withBackupCode();
+      });
 
       fixtures.clerk.user?.phoneNumbers[0].setReservedForSecondFactor.mockResolvedValue({} as PhoneNumberResource);
       const { getByText, userEvent, getByRole } = render(<MfaSection />, { wrapper });
@@ -132,7 +139,12 @@ describe('MfaPage', () => {
       getByText(
         /Save these backup codes and store them somewhere safe. If you lose access to your authentication device, you can use backup codes to sign in./i,
       );
-      getByText(/backup codes/i);
+
+      const backupCodesTitle = getByText(/backup codes/i, {
+        selector: '[data-localization-key="userProfile.backupCodePage.title__codelist"]',
+      });
+
+      expect(backupCodesTitle).toBeInTheDocument();
 
       await userEvent.click(getByRole('button', { name: /finish/i }));
     });