refactor(ui): extract ConfigureSSOWizard and lift data ownership to the host

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};

.changeset/big-files-shop.md

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

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

@@ -10,10 +10,9 @@ import { ProfileCard } from '@/elements/ProfileCard';
 import { ExclamationTriangle } from '@/icons';
 import { Route, Switch } from '@/router';
 
-import { ConfigureSSOProvider } from './ConfigureSSOContext';
 import { ConfigureSSONavbar } from './ConfigureSSONavbar';
 import { ConfigureSSOSkeleton } from './ConfigureSSOSkeleton';
-import { ConfigureSSOSteps } from './ConfigureSSOSteps';
+import { ConfigureSSOWizard } from './ConfigureSSOWizard';
 import { ProfileCardFooter, ProfileCardHeader } from './elements/ProfileCard';
 import { Step } from './elements/Step';
 import { useOrganizationEnterpriseConnection } from './hooks/useOrganizationEnterpriseConnection';
@@ -44,7 +43,7 @@ const AuthenticatedContent = withCoreUserGuard(() => {
  );
 });
 
-export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
+const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObject<HTMLDivElement> }) => {
  const {
  isLoading,
  enterpriseConnection,
@@ -54,31 +53,27 @@ export const ConfigureSSOContent = ({ contentRef }: { contentRef: React.RefObjec
  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
- // when a connection exists at load, so a cold landing on the test step is
- // covered by the full skeleton here.
+ // Gate loading above the provider so the context never observes a loading state.
  if (isLoading) {
  return <ConfigureSSOSkeleton />;
  }
 
  return (
  <ConfigureSSOProtect>
- <ConfigureSSOProvider
+ <ConfigureSSOWizard
  organizationEnterpriseConnection={organizationEnterpriseConnection}
  testRuns={testRuns}
  enterpriseConnection={enterpriseConnection}
  contentRef={contentRef}
  mutations={mutations}
  primaryEmailAddress={primaryEmailAddress}
- >
- <ConfigureSSOSteps />
- </ConfigureSSOProvider>
+ />
  </ConfigureSSOProtect>
  );
 };
 
-const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
+/** Permission gate shared by the wizard's hosts — personal workspaces pass, since there is no membership to check. */
+export const ConfigureSSOProtect = ({ children }: { children: React.ReactNode }) => {
  const { session } = useSession();
  const isPersonalWorkspace = !session?.lastActiveOrganizationId;
  const canManageEnterpriseConnections = useProtect(

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

@@ -0,0 +1,67 @@
+import React, { type ComponentProps } from 'react';
+
+import { CardStateProvider } from '@/elements/contexts';
+
+import { ConfigureSSOProvider } from './ConfigureSSOContext';
+import { ConfigureSSOHeader } from './ConfigureSSOHeader';
+import { type WizardStepConfig } from './elements/Wizard';
+import { Wizard } from './elements/Wizard';
+import { ConfigureStep, ConfirmationStep, SelectProviderStep, TestConfigurationStep, VerifyDomainStep } from './steps';
+
+export type ConfigureSSOWizardProps = Omit<ComponentProps<typeof ConfigureSSOProvider>, 'children'>;
+
+/** Pure, data-injected ConfigureSSO flow — hosts own fetching, loading, and permission gating. */
+export const ConfigureSSOWizard = (props: ConfigureSSOWizardProps): JSX.Element => {
+ // Guards read from props, not `useConfigureSSO()` — this component renders the provider, so the hook would throw here.
+ const { organizationEnterpriseConnection: c } = props;
+
+ const steps = React.useMemo<WizardStepConfig[]>(
+ () => [
+ { id: 'verify-domain', label: 'Verify domain' },
+ { id: 'select-provider', guard: () => c.isPrimaryEmailVerified },
+ { id: 'configure', label: 'Configure', guard: () => c.isPrimaryEmailVerified && c.hasConnection },
+ { id: 'test', label: 'Test', guard: () => c.hasMinimumConfiguration || c.isActive },
+ { id: 'confirmation', label: 'Confirmation', guard: () => c.hasSuccessfulTestRun || c.isActive },
+ ],
+ [c],
+ );
+
+ // Each step owns a `CardStateProvider` so card errors stay scoped to their step and clear when it unmounts.
+ return (
+ <ConfigureSSOProvider {...props}>
+ <Wizard steps={steps}>
+ <ConfigureSSOHeader />
+
+ <Wizard.Match id='verify-domain'>
+ <CardStateProvider>
+ <VerifyDomainStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='select-provider'>
+ <CardStateProvider>
+ <SelectProviderStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='configure'>
+ <CardStateProvider>
+ <ConfigureStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='test'>
+ <CardStateProvider>
+ <TestConfigurationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+
+ <Wizard.Match id='confirmation'>
+ <CardStateProvider>
+ <ConfirmationStep />
+ </CardStateProvider>
+ </Wizard.Match>
+ </Wizard>
+ </ConfigureSSOProvider>
+ );
+};

packages/ui/src/components/ConfigureSSO/__tests__/ConfigureSSO.navigation.test.tsx

@@ -7,7 +7,7 @@ import { ConfigureSSO } from '../ConfigureSSO';
 
 // Integration coverage for the wizard's navigation contract at the rendered-
 // component level — the real `ConfigureSSO` → `useOrganizationEnterpriseConnection`
-// → `ConfigureSSOSteps` → `<Wizard>` → `useWizardMachine` → step wiring, driven
+// → `ConfigureSSOWizard` → `<Wizard>` → `useWizardMachine` → step wiring, driven
 // only through the connection data the (auto-mocked) FAPI handles return. The
 // machine-level behaviours (defer/resolve, clamp) are unit-tested in
 // `useWizardMachine.test.tsx`; these tests prove those behaviours hold when the

packages/ui/src/components/ConfigureSSO/domain/__tests__/organizationEnterpriseConnection.test.ts

@@ -146,6 +146,72 @@ describe('organizationEnterpriseConnection', () => {
  });
  });
 
+ describe('status', () => {
+ it('undefined connection → unconfigured', () => {
+ expect(derive({ connection: undefined }).status).toBe('unconfigured');
+ });
+ it('null connection → unconfigured', () => {
+ expect(derive({ connection: null }).status).toBe('unconfigured');
+ });
+ it('created but unconfigured connection → in_progress', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: null }) }).status).toBe('in_progress');
+ });
+ it('partially configured connection → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({
+ samlConnection: makeSamlConnection({ idpSsoUrl: 'https://idp.example.com/sso' }),
+ }),
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured but not yet successfully tested → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('successfully tested but not minimally configured → in_progress', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('in_progress');
+ });
+ it('configured + successfully tested + not active → inactive', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: false }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('inactive');
+ });
+ it('active connection → active', () => {
+ expect(derive({ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }) }).status).toBe(
+ 'active',
+ );
+ });
+ it('active wins over configured + successfully tested', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: fullyConfiguredSaml, active: true }),
+ hasSuccessfulTestRun: true,
+ }).status,
+ ).toBe('active');
+ });
+ it('active wins even for an unconfigured, untested connection', () => {
+ expect(
+ derive({
+ connection: makeConnection({ samlConnection: null, active: true }),
+ hasSuccessfulTestRun: false,
+ }).status,
+ ).toBe('active');
+ });
+ });
+
  it('is pure: identical inputs produce a deep-equal entity', () => {
  const connection = makeConnection({ samlConnection: fullyConfiguredSaml, active: true });
  const primaryEmail = makeEmail('verified');
@@ -168,6 +234,7 @@ describe('organizationEnterpriseConnection', () => {
  hasMinimumConfiguration: true,
  isPrimaryEmailVerified: true,
  hasSuccessfulTestRun: true,
+ status: 'active',
  });
  });
 });

packages/ui/src/components/ConfigureSSO/domain/organizationEnterpriseConnection.ts

@@ -23,12 +23,14 @@ export const connectionBackingEmail = (user: UserResource | null | undefined): E
 export interface OrganizationEnterpriseConnectionInput {
  /** FAPI currently supports a single connection per organization. */
  connection: EnterpriseConnectionResource | null | undefined;
- /** The email address whose domain backs the connection. */
  primaryEmail: EmailAddressResource | null | undefined;
  /** Probed upstream — not a property of the connection resource itself. */
  hasSuccessfulTestRun: boolean;
 }
 
+/** Display-facing lifecycle summary — the wizard's navigation guards keep reading the raw booleans. */
+export type OrganizationEnterpriseConnectionStatus = 'unconfigured' | 'in_progress' | 'active' | 'inactive';
+
 /**
  * The active organization's SSO-config domain entity: an immutable, pure value
  * object the wizard makes every flow decision from. A snapshot of flattened booleans/values.
@@ -40,22 +42,51 @@ export interface OrganizationEnterpriseConnection {
  readonly hasMinimumConfiguration: boolean;
  readonly isPrimaryEmailVerified: boolean;
  readonly hasSuccessfulTestRun: boolean;
+ readonly status: OrganizationEnterpriseConnectionStatus;
 }
 
 // TODO - Update to support OpenID Connect
 export const isEnterpriseConnectionConfigured = (
  connection: EnterpriseConnectionResource | null | undefined,
 ): boolean => Boolean(connection?.samlConnection?.idpSsoUrl && connection?.samlConnection?.idpEntityId);
 
+const connectionStatus = ({
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ hasSuccessfulTestRun,
+}: Pick<
+ OrganizationEnterpriseConnection,
+ 'hasConnection' | 'isActive' | 'hasMinimumConfiguration' | 'hasSuccessfulTestRun'
+>): OrganizationEnterpriseConnectionStatus => {
+ if (!hasConnection) {
+ return 'unconfigured';
+ }
+ if (isActive) {
+ return 'active';
+ }
+ if (hasMinimumConfiguration && hasSuccessfulTestRun) {
+ return 'inactive';
+ }
+ return 'in_progress';
+};
+
 export const organizationEnterpriseConnection = ({
  connection,
  primaryEmail,
  hasSuccessfulTestRun,
-}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => ({
- provider: connection?.provider as ProviderType | undefined,
- hasConnection: Boolean(connection),
- isActive: Boolean(connection?.active),
- hasMinimumConfiguration: isEnterpriseConnectionConfigured(connection),
- isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
- hasSuccessfulTestRun,
-});
+}: OrganizationEnterpriseConnectionInput): OrganizationEnterpriseConnection => {
+ const hasConnection = Boolean(connection);
+ const isActive = Boolean(connection?.active);
+ const hasMinimumConfiguration = isEnterpriseConnectionConfigured(connection);
+
+ return {
+ provider: connection?.provider as ProviderType | undefined,
+ hasConnection,
+ isActive,
+ hasMinimumConfiguration,
+ isPrimaryEmailVerified: primaryEmail?.verification?.status === 'verified',
+ hasSuccessfulTestRun,
+ status: connectionStatus({ hasConnection, isActive, hasMinimumConfiguration, hasSuccessfulTestRun }),
+ };
+};