feat(clerk-js,shared): Refactor useReverification to support custom UIs (#5396)

Author: octoper

.changeset/pretty-months-wonder.md

@@ -0,0 +1,9 @@
+---
+'@clerk/react-router': patch
+'@clerk/clerk-js': patch
+'@clerk/nextjs': patch
+'@clerk/clerk-react': patch
+'@clerk/remix': patch
+---
+
+Export `isReverificationCancelledError` error helper

.changeset/tricky-deers-know.md

@@ -0,0 +1,73 @@
+---
+'@clerk/shared': minor
+'@clerk/clerk-js': patch
+---
+
+This introducing changes to `useReverification`, the changes include removing the array and returning the fetcher directly and also the dropping the options `throwOnCancel` and `onCancel` in favour of always throwing the cancellation error.
+
+```tsx {{ filename: 'src/components/MyButton.tsx' }}
+import { useReverification } from '@clerk/clerk-react'
+import { isReverificationCancelledError } from '@clerk/clerk-react/error'
+
+type MyData = {
+  balance: number
+}
+
+export function MyButton() {
+  const fetchMyData = () => fetch('/api/balance').then(res=> res.json() as Promise<MyData>)
+  const enhancedFetcher = useReverification(fetchMyData);
+  
+  const handleClick = async () => {
+    try {
+      const myData = await enhancedFetcher()
+      //     ^ is typed as `MyData`
+    } catch (e) {
+      // Handle error returned from the fetcher here
+      // You can also handle cancellation with the following
+      if (isReverificationCancelledError(err)) {
+        // Handle the cancellation error here
+      }
+    }
+  }
+
+  return <button onClick={handleClick}>Update User</button>
+}
+```
+
+These changes are also adding a new handler in options called `onNeedsReverification`, which can be used to create a custom UI
+to handle re-verification flow. When the handler is passed the default UI our AIO components provide will not be triggered so you will have to create and handle the re-verification process.
+
+
+```tsx {{ filename: 'src/components/MyButtonCustom.tsx' }}
+import { useReverification } from '@clerk/clerk-react'
+import { isReverificationCancelledError } from '@clerk/clerk-react/error'
+
+type MyData = {
+  balance: number
+}
+
+export function MyButton() {
+  const fetchMyData = () => fetch('/api/balance').then(res=> res.json() as Promise<MyData>)
+  const enhancedFetcher = useReverification(fetchMyData, {
+    onNeedsReverification: ({ complete, cancel, level }) => {
+      // e.g open a modal here and handle the re-verification flow
+    }
+  })
+
+  const handleClick = async () => {
+    try {
+      const myData = await enhancedFetcher()
+      //     ^ is typed as `MyData`
+    } catch (e) {
+      // Handle error returned from the fetcher here
+
+      // You can also handle cancellation with the following
+      if (isReverificationCancelledError(err)) {
+        // Handle the cancellation error here
+      }
+    }
+  }
+
+  return <button onClick={handleClick}>Update User</button>
+}
+```

integration/templates/next-app-router/src/app/(reverification)/action-with-use-reverification/page.tsx

@@ -4,7 +4,7 @@ import { useReverification } from '@clerk/nextjs';
 import { logUserIdActionReverification } from '@/app/(reverification)/actions';
 
 function Page() {
-  const [logUserWithReverification] = useReverification(logUserIdActionReverification);
+  const logUserWithReverification = useReverification(logUserIdActionReverification);
   const [pending, startTransition] = useTransition();
   const [res, setRes] = useState(null);
 

integration/tests/reverification.test.ts

@@ -144,11 +144,8 @@ testAgainstRunningApps({ withEnv: [appConfigs.envs.withReverification] })(
       await u.page.getByRole('button', { name: /^add$/i }).click();
 
       await u.po.userVerification.waitForMounted();
-
       await u.po.userVerification.closeReverificationModal();
-
       await u.po.userVerification.waitForClosed();
-      await u.po.userProfile.enterTestOtpCode();
 
       await expect(u.page.locator('.cl-profileSectionItem__emailAddresses')).not.toContainText(newFakeEmail);
     });

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
   "files": [
     { "path": "./dist/clerk.js", "maxSize": "580kB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "78.5kB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "78.6kB" },
     { "path": "./dist/clerk.headless.js", "maxSize": "55KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "94KB" },
     { "path": "./dist/vendors*.js", "maxSize": "30KB" },

packages/clerk-js/src/ui/common/RemoveResourceForm.tsx

@@ -17,7 +17,7 @@ type RemoveFormProps = FormProps & {
 export const RemoveResourceForm = withCardStateProvider((props: RemoveFormProps) => {
   const { title, messageLine1, messageLine2, deleteResource, onSuccess, onReset } = props;
   const card = useCardState();
-  const [deleteWithReverification] = useReverification(deleteResource);
+  const deleteWithReverification = useReverification(deleteResource);
 
   const handleSubmit = async () => {
     try {

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

@@ -6,7 +6,7 @@ import { FullHeightLoader, ProfileSection, ThreeDotsMenu } from '../../elements'
 import { useFetch, useLoadingStatus } from '../../hooks';
 import { DeviceLaptop, DeviceMobile } from '../../icons';
 import { mqu, type PropsOfComponent } from '../../styledSystem';
-import { getRelativeToNowDateKey } from '../../utils';
+import { getRelativeToNowDateKey, handleError } from '../../utils';
 import { currentSessionFirst } from './utils';
 
 export const ActiveDevicesSection = () => {
@@ -54,19 +54,16 @@ const isSignedInStatus = (status: string): status is SignedInSessionResource['st
 const DeviceItem = ({ session }: { session: SessionWithActivitiesResource }) => {
   const isCurrent = useSession().session?.id === session.id;
   const status = useLoadingStatus();
-  const [revokeSession] = useReverification(session.revoke.bind(session));
+  const revokeSession = useReverification(session.revoke.bind(session));
 
   const revoke = async () => {
     if (isCurrent || !session) {
       return;
     }
     status.setLoading();
-    return (
-      revokeSession()
-        // TODO-STEPUP: Properly handler the response with a setCardError
-        .catch(() => {})
-        .finally(() => status.setIdle())
-    );
+    return revokeSession()
+      .catch(err => handleError(err, [], status.setError))
+      .finally(() => status.setIdle());
   };
 
   return (
@@ -76,15 +73,14 @@ const DeviceItem = ({ session }: { session: SessionWithActivitiesResource }) =>
       elementId={isCurrent ? descriptors.activeDeviceListItem.setId('current') : undefined}
       sx={{
         alignItems: 'flex-start',
+        opacity: status.isLoading ? 0.5 : 1,
       }}
+      isDisabled={status.isLoading}
     >
-      {status.isLoading && <FullHeightLoader />}
-      {!status.isLoading && (
-        <>
-          <DeviceInfo session={session} />
-          {!isCurrent && <ActiveDeviceMenu revoke={revoke} />}
-        </>
-      )}
+      <>
+        <DeviceInfo session={session} />
+        {!isCurrent && <ActiveDeviceMenu revoke={revoke} />}
+      </>
     </ProfileSection.Item>
   );
 };

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

@@ -28,7 +28,7 @@ export const AddAuthenticatorApp = withCardStateProvider((props: AddAuthenticato
   const { title, onSuccess, onReset } = props;
   const { user } = useUser();
   const card = useCardState();
-  const [createTOTP] = useReverification(() => user?.createTOTP());
+  const createTOTP = useReverification(() => user?.createTOTP());
   const { close } = useActionContext();
   const [totp, setTOTP] = React.useState<TOTPResource | undefined>(undefined);
   const [displayFormat, setDisplayFormat] = React.useState<DisplayFormat>('qr');

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

@@ -19,7 +19,7 @@ const ConnectMenuButton = (props: { strategy: OAuthStrategy; onClick?: () => voi
   const { additionalOAuthScopes, componentName, mode } = useUserProfileContext();
   const isModal = mode === 'modal';
 
-  const [createExternalAccount] = useReverification(() => {
+  const createExternalAccount = useReverification(() => {
     const socialProvider = strategy.replace('oauth_', '') as OAuthProvider;
     const redirectUrl = isModal
       ? appendModalState({ url: window.location.href, componentName, socialProvider: socialProvider })

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

@@ -104,7 +104,7 @@ const ConnectedAccount = ({ account }: { account: ExternalAccountResource }) =>
       })
     : window.location.href;
 
-  const [createExternalAccount] = useReverification(() =>
+  const createExternalAccount = useReverification(() =>
     user?.createExternalAccount({
       strategy: account.verification!.strategy as OAuthStrategy,
       redirectUrl,