refactor(ui): drive ConfigureSSO wizard navigation with a state machine

.changeset/coral-rivers-bloom.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Refactor `<ConfigureSSO />` to drive its wizard navigation through an internal state machine. Step routing now lives in a single pure reducer instead of inside individual steps, data is fetched once through a single hook, and all connection mutations are centralized and wrapped with reverification. No changes to the public API.

packages/shared/src/react/hooks/useOrganizationEnterpriseConnections.tsx

@@ -77,28 +77,45 @@ function useOrganizationEnterpriseConnections(
   const createEnterpriseConnection = useCallback(
     async (createParams: CreateOrganizationEnterpriseConnectionParams) => {
       const created = await organization?.createEnterpriseConnection(createParams);
-      await revalidate();
+
+      queryClient.setQueryData(queryKey, (prev: EnterpriseConnectionResource[]) => {
+        return [...prev, created];
+      });
+
       return created;
     },
-    [organization, revalidate],
+    [organization, queryClient, queryKey],
   );
 
   const updateEnterpriseConnection = useCallback(
     async (enterpriseConnectionId: string, updateParams: UpdateOrganizationEnterpriseConnectionParams) => {
       const updated = await organization?.updateEnterpriseConnection(enterpriseConnectionId, updateParams);
-      await revalidate();
+
+      queryClient.setQueryData(queryKey, (prev: EnterpriseConnectionResource[]) => {
+        return prev.map(connection => {
+          if (connection.id === enterpriseConnectionId) {
+            return updated;
+          }
+          return connection;
+        });
+      });
+
       return updated;
     },
-    [organization, revalidate],
+    [organization, queryClient, queryKey],
   );
 
   const deleteEnterpriseConnection = useCallback(
     async (enterpriseConnectionId: string) => {
       const deleted = await organization?.deleteEnterpriseConnection(enterpriseConnectionId);
-      await revalidate();
+
+      queryClient.setQueryData(queryKey, (prev: EnterpriseConnectionResource[]) => {
+        return prev.filter(connection => connection.id !== enterpriseConnectionId);
+      });
+
       return deleted;
     },
-    [organization, revalidate],
+    [organization, queryClient, queryKey],
   );
 
   return {

packages/ui/src/components/ConfigureSSO/ConfigureSSO.tsx

@@ -1,27 +1,22 @@
-import {
-  __internal_useOrganizationEnterpriseConnections,
-  __internal_useOrganizationEnterpriseConnectionTestRuns,
-  useSession,
-} from '@clerk/shared/react';
-import type { ConfigureSSOProps, EnterpriseConnectionResource } from '@clerk/shared/types';
+import { useSession } from '@clerk/shared/react';
+import type { ConfigureSSOProps } from '@clerk/shared/types';
 import React from 'react';
 
 import { useProtect } from '@/common';
 import { withCoreUserGuard } from '@/contexts';
 import { Col, Flex, Flow, Heading, Icon, localizationKeys, Text } from '@/customizables';
-import { useCardState, withCardStateProvider } from '@/elements/contexts';
+import { withCardStateProvider } from '@/elements/contexts';
 import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider, useConfigureSSO } from './ConfigureSSOContext';
-import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
+import { ConfigureSSOSteps } from './ConfigureSSOSteps';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
-import { useWizard, Wizard } from './elements/Wizard';
-import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
 
 const ConfigureSSOInternal = () => {
   return (
@@ -51,90 +46,37 @@ const AuthenticatedContent = withCoreUserGuard(() => {
 
 export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
   const {
-    data: enterpriseConnections,
-    isLoading: isLoadingEnterpriseConnections,
-    createEnterpriseConnection,
-    updateEnterpriseConnection,
-    deleteEnterpriseConnection,
-  } = __internal_useOrganizationEnterpriseConnections({ enabled: true });
-  // Currently the self-serve SSO UI flow only supports one enterprise connection per organization
-  const enterpriseConnection = enterpriseConnections?.[0];
-
-  const { hasSuccessfulTestRun, isLoading: isLoadingTestRuns } = useHasSuccessfulTestRun(enterpriseConnection);
-
-  const isLoading = isLoadingEnterpriseConnections || isLoadingTestRuns;
+    isLoading,
+    enterpriseConnection,
+    organizationEnterpriseConnection,
+    testRuns,
+    mutations,
+    primaryEmailAddress,
+  } = useOrganizationEnterpriseConnection();
+
+  // Gate loading one level above the provider so the context never observes a
+  // loading state. The single test-run source is part of this initial fetch, so
+  // a cold landing on the test step is covered by the full skeleton here.
   if (isLoading) {
     return <ConfigureSSOSkeleton />;
   }
 
   return (
     <ConfigureSSOProtect>
       <ConfigureSSOProvider
-        hasSuccessfulTestRun={hasSuccessfulTestRun}
+        organizationEnterpriseConnection={organizationEnterpriseConnection}
+        testRuns={testRuns}
         enterpriseConnection={enterpriseConnection}
         contentRef={contentRef}
-        createEnterpriseConnection={createEnterpriseConnection}
-        updateEnterpriseConnection={updateEnterpriseConnection}
-        deleteEnterpriseConnection={deleteEnterpriseConnection}
+        mutations={mutations}
+        primaryEmailAddress={primaryEmailAddress}
       >
         <ConfigureSSOSteps />
       </ConfigureSSOProvider>
     </ConfigureSSOProtect>
   );
 };
 
-const ConfigureSSOSteps = () => {
-  const { initialStepId, enterpriseConnection } = useConfigureSSO();
-
-  return (
-    <Wizard initialStepId={initialStepId}>
-      <ResetCardErrorOnStepChange />
-      <ConfigureSSOHeader />
-
-      {/*
-       * `select-provider` is only a wizard step while there's no enterprise
-       * connection yet — creating one unregisters this step, which:
-       *   1. Hides it from the breadcrumb (no need for a manual filter), and
-       *   2. Prevents `goPrev` from any later step (e.g. configure's first
-       *      substep) from ever bubbling back into provider selection.
-       */}
-      {!enterpriseConnection && (
-        <Wizard.Step id='select-provider'>
-          <SelectProviderStep />
-        </Wizard.Step>
-      )}
-
-      <Wizard.Step
-        id='verify-domain'
-        label='Verify domain'
-      >
-        <VerifyDomainStep />
-      </Wizard.Step>
-
-      <Wizard.Step
-        id='configure'
-        label='Configure'
-      >
-        <ConfigureStep />
-      </Wizard.Step>
-
-      <Wizard.Step
-        id='test'
-        label='Test'
-      >
-        <TestConfigurationStep />
-      </Wizard.Step>
-
-      <Wizard.Step
-        id='confirmation'
-        label='Confirmation'
-      >
-        <ConfirmationStep />
-      </Wizard.Step>
-    </Wizard>
-  );
-};
-
 const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
   const { session } = useSession();
   const isPersonalWorkspace = !session?.lastActiveOrganizationId;
@@ -193,44 +135,4 @@ const MissingManageEnterpriseConnectionsPermission = () => (
   </>
 );
 
-/**
- * Sentinel component rendered inside `<Wizard>`
- *
- * Clears any card-level error whenever the active step transitions, so a stale failure from one step
- * doesn't leak into the next
- */
-const ResetCardErrorOnStepChange = (): null => {
-  const { currentStep } = useWizard();
-  const card = useCardState();
-  const previousStepIdRef = React.useRef(currentStep?.id);
-
-  React.useEffect(() => {
-    if (previousStepIdRef.current === currentStep?.id) {
-      return;
-    }
-
-    previousStepIdRef.current = currentStep?.id;
-    card.setError(undefined);
-  }, [currentStep?.id, card]);
-
-  return null;
-};
-
-/**
- * Fetches a single successful test run for the given connection on mount
- */
-const useHasSuccessfulTestRun = (
-  enterpriseConnection: EnterpriseConnectionResource | undefined,
-): { hasSuccessfulTestRun: boolean; isLoading: boolean } => {
-  const { data: successfulTestRuns, isLoading } = __internal_useOrganizationEnterpriseConnectionTestRuns({
-    enterpriseConnectionId: enterpriseConnection?.id ?? null,
-    params: { initialPage: 1, pageSize: 1, status: ['success'] },
-  });
-
-  return {
-    hasSuccessfulTestRun: (successfulTestRuns?.length ?? 0) > 0,
-    isLoading,
-  };
-};
-
 export const ConfigureSSO: React.ComponentType<ConfigureSSOProps> = withCardStateProvider(ConfigureSSOInternal);