feat(clerk-js): Improve redirects on OAuth callback

.changeset/tender-icons-bake.md

@@ -0,0 +1,2 @@
+---
+---

packages/clerk-js/src/core/clerk.test.ts

@@ -700,6 +700,8 @@ describe('Clerk singleton', () => {
           signIn: new SignIn(null),
           signUp: new SignUp({
             status: 'missing_requirements',
+            missing_fields: [],
+            unverified_fields: [],
             verifications: {
               external_account: {
                 status: 'unverified',
@@ -1111,6 +1113,8 @@ describe('Clerk singleton', () => {
           signIn: new SignIn(null),
           signUp: new SignUp({
             status: 'missing_requirements',
+            missing_fields: ['last_name'],
+            unverified_fields: [],
             verifications: {
               external_account: {
                 status: 'verified',

packages/clerk-js/src/core/clerk.ts

@@ -53,6 +53,7 @@ import type {
 } from '@clerk/types';
 
 import type { MountComponentRenderer } from '../ui/Components';
+import { handleMissingRequirements } from '../ui/components/SignUp/util';
 import {
   appendAsQueryParams,
   buildURL,
@@ -834,6 +835,8 @@ export default class Clerk implements ClerkInterface {
     const { externalAccount } = signUp.verifications;
     const su = {
       status: signUp.status,
+      missingFields: signUp.missingFields,
+      unverifiedFields: signUp.unverifiedFields,
       externalAccountStatus: externalAccount.status,
       externalAccountErrorCode: externalAccount.error?.code,
       externalAccountSessionId: externalAccount.error?.meta?.sessionId,
@@ -873,6 +876,23 @@ export default class Clerk implements ClerkInterface {
         buildURL({ base: displayConfig.signUpUrl, hashPath: '/continue' }, { stringify: true }),
     );
 
+    const navigateToNextStepSignUp = () => {
+      if (su.unverifiedFields.length === 0 || su.missingFields.length !== 0) {
+        return navigateToContinueSignUp();
+      }
+
+      return handleMissingRequirements({
+        signUp,
+        verifyEmailPath:
+          params.verifyEmailAddressUrl ||
+          buildURL({ base: displayConfig.signUpUrl, hashPath: '/verify-email-address' }, { stringify: true }),
+        verifyPhonePath:
+          params.verifyPhoneNumberUrl ||
+          buildURL({ base: displayConfig.signUpUrl, hashPath: '/verify-phone-number' }, { stringify: true }),
+        navigate,
+      });
+    };
+
     const userExistsButNeedsToSignIn =
       su.externalAccountStatus === 'transferable' && su.externalAccountErrorCode === 'external_account_exists';
 
@@ -902,7 +922,7 @@ export default class Clerk implements ClerkInterface {
             beforeEmit: navigateAfterSignUp,
           });
         case 'missing_requirements':
-          return navigateToContinueSignUp();
+          return navigateToNextStepSignUp();
         default:
           clerkOAuthCallbackDidNotCompleteSignInSignUp('sign in');
       }
@@ -938,7 +958,7 @@ export default class Clerk implements ClerkInterface {
     }
 
     if (su.externalAccountStatus === 'verified' && su.status === 'missing_requirements') {
-      return navigateToContinueSignUp();
+      return navigateToNextStepSignUp();
     }
 
     return navigateToSignIn();

packages/clerk-js/src/ui/components/SignUp/SignUp.tsx

@@ -44,6 +44,8 @@ function SignUpRoutes(): JSX.Element {
             redirectUrl={signUpContext.redirectUrl}
             secondFactorUrl={signUpContext.secondFactorUrl}
             continueSignUpUrl='../continue'
+            verifyEmailAddressUrl='../verify-email-address'
+            verifyPhoneNumberUrl='../verify-phone-number'
           />
         </Route>
         <Route path='verify'>

packages/clerk-js/src/ui/components/SignUp/__tests__/SignUpContinue.test.tsx

@@ -42,7 +42,9 @@ describe('SignUpContinue', () => {
       f.startSignUpWithEmailAddress();
     });
     render(<SignUpContinue />, { wrapper });
-    screen.getByText(/email address/i);
+    // Because the email address is already set, it should not be shown,
+    // as we're in PSU mode and it's not a missing field.
+    expect(screen.queryByText(/email address/i)).not.toBeInTheDocument();
     screen.getByText(/password/i);
   });
 

packages/clerk-js/src/ui/components/SignUp/signUpFormHelpers.ts

@@ -50,12 +50,13 @@ export function determineActiveFields(fieldProps: FieldDeterminationProps): Fiel
 // If continuing with an existing sign-up, show only fields absolutely necessary to minimize fiction
 export function minimizeFieldsForExistingSignup(fields: Fields, signUp: SignUpResource) {
   if (signUp) {
+    const hasEmailFilled = !!signUp.emailAddress;
     const hasVerifiedEmail = signUp.verifications?.emailAddress?.status == 'verified';
     const hasVerifiedPhone = signUp.verifications?.phoneNumber?.status == 'verified';
     const hasVerifiedExternalAccount = signUp.verifications?.externalAccount?.status == 'verified';
     const hasVerifiedWeb3Wallet = signUp.verifications?.web3Wallet?.status == 'verified';
 
-    if (hasVerifiedEmail) {
+    if (hasEmailFilled || hasVerifiedEmail) {
       delete fields.emailAddress;
     }
 

packages/clerk-js/src/ui/components/SignUp/util.ts

@@ -10,6 +10,32 @@ type CompleteSignUpFlowProps = {
   redirectUrlComplete?: string;
 };
 
+export const handleMissingRequirements = ({
+  signUp,
+  verifyEmailPath,
+  verifyPhonePath,
+  navigate,
+  redirectUrl = '',
+  redirectUrlComplete = '',
+}: CompleteSignUpFlowProps): Promise<unknown> | undefined => {
+  if (signUp.missingFields.some(mf => mf === 'saml')) {
+    return signUp.authenticateWithRedirect({
+      strategy: 'saml',
+      redirectUrl,
+      redirectUrlComplete,
+      continueSignUp: true,
+    });
+  }
+
+  if (signUp.unverifiedFields?.includes('email_address') && verifyEmailPath) {
+    return navigate(verifyEmailPath);
+  }
+  if (signUp.unverifiedFields?.includes('phone_number') && verifyPhonePath) {
+    return navigate(verifyPhonePath);
+  }
+  return;
+};
+
 export const completeSignUpFlow = ({
   signUp,
   verifyEmailPath,
@@ -19,24 +45,18 @@ export const completeSignUpFlow = ({
   redirectUrl = '',
   redirectUrlComplete = '',
 }: CompleteSignUpFlowProps): Promise<unknown> | undefined => {
-  if (signUp.status === 'complete') {
-    return handleComplete && handleComplete();
-  } else if (signUp.status === 'missing_requirements') {
-    if (signUp.missingFields.some(mf => mf === 'saml')) {
-      return signUp.authenticateWithRedirect({
-        strategy: 'saml',
+  switch (signUp.status) {
+    case 'complete':
+      return handleComplete && handleComplete();
+    case 'missing_requirements':
+      return handleMissingRequirements({
+        signUp,
+        verifyEmailPath,
+        verifyPhonePath,
+        navigate,
         redirectUrl,
         redirectUrlComplete,
-        continueSignUp: true,
       });
-    }
-
-    if (signUp.unverifiedFields?.includes('email_address') && verifyEmailPath) {
-      return navigate(verifyEmailPath);
-    }
-    if (signUp.unverifiedFields?.includes('phone_number') && verifyPhonePath) {
-      return navigate(verifyPhonePath);
-    }
   }
   return;
 };

packages/types/src/clerk.ts

@@ -451,6 +451,16 @@ export type HandleOAuthCallbackParams = {
    * Full URL or path to navigate after an incomplete sign up.
    */
   continueSignUpUrl?: string | null;
+
+  /**
+   * Full URL or path to navigate after requesting email verification.
+   */
+  verifyEmailAddressUrl?: string | null;
+
+  /**
+   * Full URL or path to navigate after requesting phone verification.
+   */
+  verifyPhoneNumberUrl?: string | null;
 };
 
 /**