feat(clerk-js,clerk-react,nextjs): Introduce <TaskSelectOrganization /> component (#6376)

Author: LauraBeatris

.changeset/bright-cats-lay.md

@@ -0,0 +1,20 @@
+---
+'@clerk/clerk-js': minor
+---
+
+Introduce `<TaskSelectOrganization />` component.
+
+It allows you to eject the organization selection task flow from the default `SignIn` and `SignUp` components and render it on custom URL paths using `taskUrls`.
+
+Usage example:
+```tsx
+<ClerkProvider taskUrls={{ 'select-organization': '/onboarding/select-organization' }}>
+  <App />
+</ClerkProvider>
+```
+
+```tsx
+function OnboardingSelectOrganization() {
+  return <TaskSelectOrganization redirectUrlComplete="/dashboard/onboarding-complete" />
+}
+```

.changeset/vast-places-tap.md

@@ -0,0 +1,5 @@
+---
+'@clerk/types': patch
+---
+
+Add TypeScript types for `<TaskSelectOrganization />` component.

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

@@ -76,6 +76,7 @@ import type {
   SignUpProps,
   SignUpRedirectOptions,
   SignUpResource,
+  TaskSelectOrganizationProps,
   UnsubscribeCallback,
   UserButtonProps,
   UserProfileProps,
@@ -1164,6 +1165,35 @@ export class Clerk implements ClerkInterface {
     void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
   };
 
+  public mountTaskSelectOrganization = (node: HTMLDivElement, props?: TaskSelectOrganizationProps) => {
+    this.assertComponentsReady(this.#componentControls);
+
+    if (disabledOrganizationsFeature(this, this.environment)) {
+      if (this.#instanceType === 'development') {
+        throw new ClerkRuntimeError(warnings.cannotRenderAnyOrganizationComponent('TaskSelectOrganization'), {
+          code: CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE,
+        });
+      }
+      return;
+    }
+
+    void this.#componentControls.ensureMounted({ preloadHint: 'TaskSelectOrganization' }).then(controls =>
+      controls.mountComponent({
+        name: 'TaskSelectOrganization',
+        appearanceKey: 'taskSelectOrganization',
+        node,
+        props,
+      }),
+    );
+
+    this.telemetry?.record(eventPrebuiltComponentMounted('TaskSelectOrganization', props));
+  };
+
+  public unmountTaskSelectOrganization = (node: HTMLDivElement) => {
+    this.assertComponentsReady(this.#componentControls);
+    void this.#componentControls.ensureMounted().then(controls => controls.unmountComponent({ node }));
+  };
+
   /**
    * `setActive` can be used to set the active session and/or organization.
    */

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

@@ -27,23 +27,25 @@ export function navigateToTask(
   routeKey: keyof typeof INTERNAL_SESSION_TASK_ROUTE_BY_KEY,
   { componentNavigationContext, globalNavigate, options, environment }: NavigateToTaskOptions,
 ) {
-  const taskRoute = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
+  const customTaskUrl = options?.taskUrls?.[routeKey];
+  const internalTaskRoute = `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[routeKey]}`;
 
-  if (componentNavigationContext) {
-    return componentNavigationContext.navigate(componentNavigationContext.indexPath + taskRoute);
+  if (componentNavigationContext && !customTaskUrl) {
+    return componentNavigationContext.navigate(componentNavigationContext.indexPath + internalTaskRoute);
   }
 
   const signInUrl = options['signInUrl'] || environment.displayConfig.signInUrl;
   const signUpUrl = options['signUpUrl'] || environment.displayConfig.signUpUrl;
   const isReferrerSignUpUrl = window.location.href.startsWith(signUpUrl);
 
-  const sessionTaskUrl = buildURL(
-    {
-      base: isReferrerSignUpUrl ? signUpUrl : signInUrl,
-      hashPath: taskRoute,
-    },
-    { stringify: true },
+  return globalNavigate(
+    customTaskUrl ??
+      buildURL(
+        {
+          base: isReferrerSignUpUrl ? signUpUrl : signInUrl,
+          hashPath: internalTaskRoute,
+        },
+        { stringify: true },
+      ),
   );
-
-  return globalNavigate(options.taskUrls?.[routeKey] ?? sessionTaskUrl);
 }

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

@@ -5,7 +5,12 @@ const formatWarning = (msg: string) => {
 };
 
 const createMessageForDisabledOrganizations = (
-  componentName: 'OrganizationProfile' | 'OrganizationSwitcher' | 'OrganizationList' | 'CreateOrganization',
+  componentName:
+    | 'OrganizationProfile'
+    | 'OrganizationSwitcher'
+    | 'OrganizationList'
+    | 'CreateOrganization'
+    | 'TaskSelectOrganization',
 ) => {
   return formatWarning(
     `The <${componentName}/> cannot be rendered when the feature is turned off. Visit 'dashboard.clerk.com' to enable the feature. Since the feature is turned off, this is no-op.`,
@@ -23,6 +28,8 @@ const warnings = {
     'The <SignUp/> component cannot render when a user is already signed in, unless the application allows multiple sessions. Since a user is signed in and this application only allows a single session, Clerk is redirecting to the value set in `afterSignUp` URL instead.',
   cannotRenderSignUpComponentWhenTaskExists:
     'The <SignUp/> component cannot render when a user has a pending task, unless the application allows multiple sessions. Since a user is signed in and this application only allows a single session, Clerk is redirecting to the task instead.',
+  cannotRenderComponentWhenTaskDoesNotExist:
+    '<TaskSelectOrganization/> cannot render unless a session task is pending. Clerk is redirecting to the value set in `redirectUrlComplete` instead.',
   cannotRenderSignInComponentWhenSessionExists:
     'The <SignIn/> component cannot render when a user is already signed in, unless the application allows multiple sessions. Since a user is signed in and this application only allows a single session, Clerk is redirecting to the `afterSignIn` URL instead.',
   cannotRenderSignInComponentWhenTaskExists:

packages/clerk-js/src/ui/components/CreateOrganization/CreateOrganizationForm.tsx

@@ -1,4 +1,4 @@
-import { useOrganization, useOrganizationList } from '@clerk/shared/react';
+import { useClerk, useOrganization, useOrganizationList } from '@clerk/shared/react';
 import type { CreateOrganizationParams, OrganizationResource } from '@clerk/types';
 import React, { useContext } from 'react';
 
@@ -41,6 +41,7 @@ export const CreateOrganizationForm = withCardStateProvider((props: CreateOrgani
   const card = useCardState();
   const wizard = useWizard({ onNextStep: () => card.setError(undefined) });
   const sessionTasksContext = useContext(SessionTasksContext);
+  const clerk = useClerk();
 
   const lastCreatedOrganizationRef = React.useRef<OrganizationResource | null>(null);
   const { createOrganization, isLoaded, setActive, userMemberships } = useOrganizationList({
@@ -89,13 +90,15 @@ export const CreateOrganizationForm = withCardStateProvider((props: CreateOrgani
       lastCreatedOrganizationRef.current = organization;
       await setActive({ organization });
 
-      void userMemberships.revalidate?.();
-
       if (sessionTasksContext) {
-        await sessionTasksContext.nextTask();
+        await clerk.__internal_navigateToTaskIfAvailable({
+          redirectUrlComplete: sessionTasksContext.redirectUrlComplete,
+        });
         return;
       }
 
+      void userMemberships.revalidate?.();
+
       if (props.skipInvitationScreen ?? organization.maxAllowedMemberships === 1) {
         return completeFlow();
       }

packages/clerk-js/src/ui/components/OrganizationList/UserMembershipList.tsx

@@ -1,4 +1,4 @@
-import { useOrganizationList, useUser } from '@clerk/shared/react';
+import { useClerk, useOrganizationList, useUser } from '@clerk/shared/react';
 import type { OrganizationResource } from '@clerk/types';
 import { useContext } from 'react';
 
@@ -15,6 +15,7 @@ export const MembershipPreview = withCardStateProvider((props: { organization: O
   const card = useCardState();
   const { navigateAfterSelectOrganization } = useOrganizationListContext();
   const { isLoaded, setActive } = useOrganizationList();
+  const clerk = useClerk();
   const sessionTasksContext = useContext(SessionTasksContext);
 
   if (!isLoaded) {
@@ -26,8 +27,10 @@ export const MembershipPreview = withCardStateProvider((props: { organization: O
         organization,
       });
 
-      if (sessionTasksContext?.nextTask) {
-        return sessionTasksContext?.nextTask();
+      if (sessionTasksContext) {
+        return clerk.__internal_navigateToTaskIfAvailable({
+          redirectUrlComplete: sessionTasksContext.redirectUrlComplete,
+        });
       }
 
       await navigateAfterSelectOrganization(organization);

packages/clerk-js/src/ui/components/SessionTasks/index.tsx

@@ -1,16 +1,20 @@
 import { useClerk } from '@clerk/shared/react';
 import { eventComponentMounted } from '@clerk/shared/telemetry';
-import { useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { useContext, useEffect, useRef } from 'react';
 
 import { Card } from '@/ui/elements/Card';
 import { withCardStateProvider } from '@/ui/elements/contexts';
 import { LoadingCardContainer } from '@/ui/elements/LoadingCard';
 
 import { INTERNAL_SESSION_TASK_ROUTE_BY_KEY } from '../../../core/sessionTasks';
 import { SignInContext, SignUpContext } from '../../../ui/contexts';
-import { SessionTasksContext, useSessionTasksContext } from '../../contexts/components/SessionTasks';
+import {
+  SessionTasksContext,
+  TaskSelectOrganizationContext,
+  useSessionTasksContext,
+} from '../../contexts/components/SessionTasks';
 import { Route, Switch, useRouter } from '../../router';
-import { ForceOrganizationSelectionTask } from './tasks/ForceOrganizationSelection';
+import { TaskSelectOrganization } from './tasks/TaskSelectOrganization';
 
 const SessionTasksStart = () => {
   const clerk = useClerk();
@@ -36,10 +40,16 @@ const SessionTasksStart = () => {
 };
 
 function SessionTaskRoutes(): JSX.Element {
+  const ctx = useSessionTasksContext();
+
   return (
     <Switch>
       <Route path={INTERNAL_SESSION_TASK_ROUTE_BY_KEY['select-organization']}>
-        <ForceOrganizationSelectionTask />
+        <TaskSelectOrganizationContext.Provider
+          value={{ componentName: 'TaskSelectOrganization', redirectUrlComplete: ctx.redirectUrlComplete }}
+        >
+          <TaskSelectOrganization />
+        </TaskSelectOrganizationContext.Provider>
       </Route>
       <Route index>
         <SessionTasksStart />
@@ -56,7 +66,6 @@ export const SessionTask = withCardStateProvider(() => {
   const { navigate } = useRouter();
   const signInContext = useContext(SignInContext);
   const signUpContext = useContext(SignUpContext);
-  const [isNavigatingToTask, setIsNavigatingToTask] = useState(false);
   const currentTaskContainer = useRef<HTMLDivElement>(null);
 
   const redirectUrlComplete =
@@ -67,10 +76,6 @@ export const SessionTask = withCardStateProvider(() => {
   // for example by using browser back navigation. Since there are no pending tasks,
   // we redirect them to their intended destination.
   useEffect(() => {
-    if (isNavigatingToTask) {
-      return;
-    }
-
     // Tasks can only exist on pending sessions, but we check both conditions
     // here to be defensive and ensure proper redirection
     const task = clerk.session?.currentTask;
@@ -80,14 +85,7 @@ export const SessionTask = withCardStateProvider(() => {
     }
 
     clerk.telemetry?.record(eventComponentMounted('SessionTask', { task: task.key }));
-  }, [clerk, navigate, isNavigatingToTask, redirectUrlComplete]);
-
-  const nextTask = useCallback(() => {
-    setIsNavigatingToTask(true);
-    return clerk
-      .__internal_navigateToTaskIfAvailable({ redirectUrlComplete })
-      .finally(() => setIsNavigatingToTask(false));
-  }, [clerk, redirectUrlComplete]);
+  }, [clerk, navigate, redirectUrlComplete]);
 
   if (!clerk.session?.currentTask) {
     return (
@@ -105,7 +103,7 @@ export const SessionTask = withCardStateProvider(() => {
   }
 
   return (
-    <SessionTasksContext.Provider value={{ nextTask, redirectUrlComplete, currentTaskContainer }}>
+    <SessionTasksContext.Provider value={{ redirectUrlComplete, currentTaskContainer }}>
       <SessionTaskRoutes />
     </SessionTasksContext.Provider>
   );