refactor(ui): drop wizard onComplete prop for parent fall-through

A nested wizard's terminal goNext now bubbles to the parent wizard's
goNext automatically — the nested wizard already holds the parent in
context, so the explicit onComplete callback was redundant. Remove
onComplete from the Wizard primitive and its callsites (the configure
sub-flow, the verify-domain inner flow, and the four SAML provider
sub-flows). A top-level wizard with no parent treats a terminal goNext
as a no-op.

Author: iagodahlem

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

@@ -22,16 +22,6 @@ interface RootProps {
    * Where `reset()` lands, force-enabled (defaults to the first declared step).
    */
   resetStepId?: string;
-  /**
-   * Terminal completion hook for the wizard's forward boundary. When the last
-   * step's `goNext` has nowhere to advance, `onComplete` is invoked instead of
-   * falling through to a parent wizard. Used by nested ConfigureSSO sub-flows
-   * to bubble their inner terminal step into the top-level wizard.
-   *
-   * NOTE: this is a transitional escape hatch; once nested flows rely purely on
-   * the parent-wizard fall-through it can be removed.
-   */
-  onComplete?: () => void;
 }
 
 const EMPTY_GUARDS: WizardGuards = {};
@@ -85,7 +75,7 @@ const deriveDescriptors = (children: React.ReactNode): WizardStepDescriptor[] =>
   return descriptors;
 };
 
-const Root = ({ children, guards, initialStepId, resetStepId, onComplete }: RootProps): JSX.Element => {
+const Root = ({ children, guards, initialStepId, resetStepId }: RootProps): JSX.Element => {
   const parentWizard = React.useContext(WizardContext);
 
   // Synchronous, render-time derivation of the step graph from JSX children.
@@ -98,7 +88,7 @@ const Root = ({ children, guards, initialStepId, resetStepId, onComplete }: Root
     [descriptors, guards, resetStepId],
   );
 
-  const value = useWizardMachine({ config, parentWizard, onComplete, initialStepId });
+  const value = useWizardMachine({ config, parentWizard, initialStepId });
 
   return <WizardContext.Provider value={value}>{children}</WizardContext.Provider>;
 };
@@ -133,8 +123,8 @@ Step.displayName = 'Wizard.Step';
  * satisfied step, gate out a step) is expressed declaratively via the named
  * `guards` record + the step's `guard` / `enabled` props — never by
  * adding/removing children. Inner sub-flows nest another `<Wizard>` inside a
- * step body; their forward boundary falls through to the parent wizard (or an
- * injected `onComplete`).
+ * step body; their forward boundary falls through to the parent wizard — a
+ * nested terminal `goNext` advances the parent automatically.
  */
 export const Wizard = Object.assign(Root, {
   Step,

packages/ui/src/components/ConfigureSSO/elements/Wizard/__tests__/Wizard.test.tsx

@@ -224,8 +224,8 @@ const NestedInner = (): JSX.Element => {
   );
 };
 
-const Nested = ({ onComplete }: { onComplete?: () => void }): JSX.Element => (
-  <Wizard onComplete={onComplete}>
+const Nested = (): JSX.Element => (
+  <Wizard>
     <NestedInner />
     <Wizard.Step id='i1'>
       <div>i1</div>
@@ -236,16 +236,11 @@ const Nested = ({ onComplete }: { onComplete?: () => void }): JSX.Element => (
   </Wizard>
 );
 
-const NestedBridge = (): JSX.Element => {
-  const { goNext } = useWizard();
-  return <Nested onComplete={goNext} />;
-};
-
 const ParentWithNested = (): JSX.Element => (
   <Wizard>
     <Probe />
     <Wizard.Step id='outer-1'>
-      <NestedBridge />
+      <Nested />
     </Wizard.Step>
     <Wizard.Step id='outer-2'>
       <div>outer-2</div>
@@ -258,13 +253,14 @@ describe('Wizard — nested sub-flows', () => {
     render(<ParentWithNested />);
 
     // Parent derives only its own two steps — the nested wizard's steps are
-    // isolated behind the Bridge component boundary.
+    // isolated behind the component boundary.
     expect(text('active')).toBe('outer-1,outer-2');
     expect(text('current')).toBe('outer-1');
     expect(screen.getByTestId('inner-current').textContent).toBe('i1');
 
-    // Advance the inner wizard to its last step, then once more → bubbles to the
-    // parent's goNext via onComplete.
+    // Advance the inner wizard to its last step, then once more → the terminal
+    // goNext bubbles to the parent's goNext automatically (the nested wizard
+    // reads the parent from context; no onComplete callback).
     click('inner-next');
     expect(screen.getByTestId('inner-current').textContent).toBe('i2');
     click('inner-next');

packages/ui/src/components/ConfigureSSO/elements/Wizard/__tests__/useWizardMachine.test.tsx

@@ -102,17 +102,37 @@ describe('useWizardMachine', () => {
     expect(result.current.current).toBe('select-provider');
   });
 
-  it('invokes onComplete when goNext has nowhere to advance', () => {
-    let completed = 0;
+  it('bubbles a terminal goNext to the parent wizard', () => {
+    let parentAdvanced = 0;
+    const parentWizard = { goNext: () => (parentAdvanced += 1) } as unknown as Parameters<
+      typeof useWizardMachine
+    >[0]['parentWizard'];
+    const { result } = renderHook(() =>
+      useWizardMachine({
+        config: config({ domainVerified: true, configured: true, tested: true, hasConnection: true }),
+        parentWizard,
+        initialStepId: 'confirmation',
+      }),
+    );
+    expect(result.current.current).toBe('confirmation');
+
+    act(() => result.current.goNext());
+
+    // Nowhere to advance inside this wizard → falls through to the parent.
+    expect(parentAdvanced).toBe(1);
+    expect(result.current.current).toBe('confirmation');
+  });
+
+  it('treats a terminal goNext as a no-op when there is no parent', () => {
     const { result } = renderMachine(
       { domainVerified: true, configured: true, tested: true, hasConnection: true },
-      { onComplete: () => (completed += 1), initialStepId: 'confirmation' },
+      { initialStepId: 'confirmation' },
     );
     expect(result.current.current).toBe('confirmation');
 
     act(() => result.current.goNext());
 
-    expect(completed).toBe(1);
+    // Top-level wizard, no parent to bubble to → stays put, no throw.
     expect(result.current.current).toBe('confirmation');
   });
 

packages/ui/src/components/ConfigureSSO/elements/Wizard/reducer.ts

@@ -127,7 +127,7 @@ export const reduce = (state: WizardState, event: WizardEvent, config: WizardCon
         }
       }
       // Nothing non-satisfied ahead — stay put (the host falls through to a
-      // parent wizard / onComplete on referential equality).
+      // parent wizard on referential equality).
       return state;
     }
 

packages/ui/src/components/ConfigureSSO/elements/Wizard/types.ts

@@ -154,8 +154,9 @@ export interface WizardContextValue {
   isLastStep: boolean;
   /**
    * Navigate forward. Walks to the next enabled, non-satisfied step. On the
-   * last step, invokes the wizard's `onComplete` (if any) or falls through to
-   * the parent wizard's `goNext`.
+   * last step, falls through to the parent wizard's `goNext` (so a nested
+   * sub-flow's terminal step advances the parent); a no-op when there is no
+   * parent.
    */
   goNext: () => void;
   /**

packages/ui/src/components/ConfigureSSO/elements/Wizard/useWizardMachine.ts

@@ -14,13 +14,12 @@ import type { WizardActiveStep, WizardContextValue } from './types';
 /**
  * Inputs the host wizard wires the machine to. The `config` carries the step
  * descriptors (derived synchronously from `<Wizard.Step>` children) + the
- * named-guards record from `<Wizard guards>`. `parentWizard`, `onComplete`, and
- * `initialStepId` support nested sub-flows and resume-from-state.
+ * named-guards record from `<Wizard guards>`. `parentWizard` and `initialStepId`
+ * support nested sub-flows and resume-from-state.
  */
 interface UseWizardMachineArgs {
   config: WizardConfig;
   parentWizard: WizardContextValue | null;
-  onComplete?: () => void;
   /**
    * Mount on this step instead of the guard-derived initial step. Used by
    * linear nested flows that resume from an externally-decided position.
@@ -36,6 +35,14 @@ interface UseWizardMachineArgs {
  * `WizardState` and feeds the reducer the CURRENT config (descriptors + guards)
  * at dispatch time.
  *
+ * ## Forward boundary: parent fall-through
+ *
+ * When a nested wizard's `goNext` lands on a step with nowhere to advance, the
+ * event bubbles to the parent wizard's `goNext` (read from `parentWizard` in
+ * context). This is how a nested sub-flow's terminal step advances the
+ * top-level wizard — no bespoke completion callback. A top-level wizard (no
+ * parent) treats a terminal `goNext` as a no-op.
+ *
  * ## Why a ref instead of a `useEffect`
  *
  * The reducer needs the latest descriptors/guards whenever an event is
@@ -47,14 +54,9 @@ interface UseWizardMachineArgs {
  * This keeps `dispatch` (and the whole nav surface) stable across renders.
  *
  * Nothing about ConfigureSSO leaks in: the hook only knows descriptors, named
- * guards, a parent wizard, and an optional completion hook.
+ * guards, and a parent wizard.
  */
-export const useWizardMachine = ({
-  config,
-  parentWizard,
-  onComplete,
-  initialStepId,
-}: UseWizardMachineArgs): WizardContextValue => {
+export const useWizardMachine = ({ config, parentWizard, initialStepId }: UseWizardMachineArgs): WizardContextValue => {
   const isNested = parentWizard !== null;
 
   // Seed lazily so the wizard mounts on the right step in a single render pass:
@@ -71,24 +73,19 @@ export const useWizardMachine = ({
   configRef.current = config;
 
   // A stable dispatch that reduces against live config and falls through to the
-  // parent wizard / onComplete when a forward step has nowhere to go. We read
-  // the parent + onComplete from refs so dispatch identity stays stable.
+  // parent wizard when a forward step has nowhere to go. We read the parent from
+  // a ref so dispatch identity stays stable.
   const parentRef = React.useRef(parentWizard);
   parentRef.current = parentWizard;
-  const onCompleteRef = React.useRef(onComplete);
-  onCompleteRef.current = onComplete;
 
   const dispatch = React.useCallback((event: WizardEvent) => {
     setState(prev => {
       const next = reduce(prev, event, configRef.current);
       // Forward fall-through: NEXT produced no transition (already on the last
-      // step). Complete into the host (onComplete) or bubble to a parent wizard.
+      // step). Bubble to the parent wizard so a nested sub-flow's terminal step
+      // advances the top-level wizard. No parent → terminal NEXT is a no-op.
       if (event.type === 'NEXT' && next === prev) {
-        if (onCompleteRef.current) {
-          onCompleteRef.current();
-        } else {
-          parentRef.current?.goNext();
-        }
+        parentRef.current?.goNext();
       }
       return next;
     });

packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/index.tsx

@@ -4,7 +4,6 @@ import { descriptors, Flow } from '@/customizables';
 
 import { useConfigureSSO } from '../../ConfigureSSOContext';
 import { Step } from '../../elements/Step';
-import { useWizard } from '../../elements/Wizard';
 import type { ProviderType } from '../../types';
 import {
   SamlCustomConfigureSteps,
@@ -13,18 +12,7 @@ import {
   SamlOktaConfigureSteps,
 } from './saml';
 
-/**
- * Props every provider sub-flow accepts. Each provider hosts its OWN nested
- * `<Wizard>` with statically-declared `<Wizard.Step>` children, so the generic
- * engine can derive its step graph at that boundary. `onComplete` bubbles the
- * inner terminal step into the top-level wizard (kept for now; a later sub-item
- * drops it for plain parent fall-through).
- */
-export type ProviderConfigureStepsProps = {
-  onComplete: () => void;
-};
-
-const STEPS_BY_PROVIDER: Record<ProviderType, (props: ProviderConfigureStepsProps) => JSX.Element> = {
+const STEPS_BY_PROVIDER: Record<ProviderType, () => JSX.Element> = {
   saml_custom: SamlCustomConfigureSteps,
   saml_okta: SamlOktaConfigureSteps,
   saml_google: SamlGoogleConfigureSteps,
@@ -33,9 +21,6 @@ const STEPS_BY_PROVIDER: Record<ProviderType, (props: ProviderConfigureStepsProp
 
 export const ConfigureStep = (): JSX.Element | null => {
   const { provider } = useConfigureSSO();
-  // Switching provider unmounts/mounts a whole nested wizard as a unit. The
-  // top-level wizard advances when the inner flow completes, via `onComplete`.
-  const { goNext } = useWizard();
 
   // Type guard, at this point the provider should have been defined
   if (!provider) {
@@ -49,13 +34,17 @@ export const ConfigureStep = (): JSX.Element | null => {
     throw new Error(`No steps found for provider: ${provider}`);
   }
 
+  // Switching provider unmounts/mounts a whole nested wizard as a unit. Each
+  // provider hosts its own nested `<Wizard>`; when its terminal step calls
+  // `goNext`, the wizard primitive bubbles it to this top-level wizard (the
+  // nested wizard's parent in context), advancing `configure` → `test`.
   return (
     <Flow.Part part='configureCreateApp'>
       <Step
         elementDescriptor={descriptors.configureSSOStep}
         elementId={descriptors.configureSSOStep.setId('configure')}
       >
-        <StepsByProvider onComplete={goNext} />
+        <StepsByProvider />
       </Step>
     </Flow.Part>
   );

packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/SamlCustomConfigureSteps.tsx

@@ -25,7 +25,6 @@ import { useConfigureSSO } from '../../../ConfigureSSOContext';
 import { Step } from '../../../elements/Step';
 import { useWizard, Wizard } from '../../../elements/Wizard';
 import { InnerStepCounter } from '../../../elements/Wizard/InnerStepCounter';
-import type { ProviderConfigureStepsProps } from '../index';
 import {
   applySamlSubmitError,
   buildSamlConfigurationPayload,
@@ -37,9 +36,9 @@ import {
   type IdpConfigurationMode,
 } from './shared/IdentityProviderConfigurationModes';
 
-export const SamlCustomConfigureSteps = ({ onComplete }: ProviderConfigureStepsProps): JSX.Element => {
+export const SamlCustomConfigureSteps = (): JSX.Element => {
   return (
-    <Wizard onComplete={onComplete}>
+    <Wizard>
       <Wizard.Step id='create-app'>
         <Step.Header
           title={localizationKeys('configureSSO.configureStep.samlCustom.mainHeaderTitle')}

packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/SamlGoogleConfigureSteps.tsx

@@ -12,7 +12,6 @@ import { useConfigureSSO } from '../../../ConfigureSSOContext';
 import { Step } from '../../../elements/Step';
 import { useWizard, Wizard } from '../../../elements/Wizard';
 import { InnerStepCounter } from '../../../elements/Wizard/InnerStepCounter';
-import type { ProviderConfigureStepsProps } from '../index';
 import {
   applySamlSubmitError,
   buildSamlConfigurationPayload,
@@ -24,9 +23,9 @@ import {
   type IdpConfigurationMode,
 } from './shared/IdentityProviderConfigurationModes';
 
-export const SamlGoogleConfigureSteps = ({ onComplete }: ProviderConfigureStepsProps): JSX.Element => {
+export const SamlGoogleConfigureSteps = (): JSX.Element => {
   return (
-    <Wizard onComplete={onComplete}>
+    <Wizard>
       <Wizard.Step id='create-app'>
         <Step.Header
           title={localizationKeys('configureSSO.configureStep.samlGoogle.mainHeaderTitle')}

packages/ui/src/components/ConfigureSSO/steps/ConfigureStep/saml/SamlMicrosoftConfigureSteps.tsx

@@ -27,7 +27,6 @@ import { useConfigureSSO } from '../../../ConfigureSSOContext';
 import { Step } from '../../../elements/Step';
 import { useWizard, Wizard } from '../../../elements/Wizard';
 import { InnerStepCounter } from '../../../elements/Wizard/InnerStepCounter';
-import type { ProviderConfigureStepsProps } from '../index';
 import {
   applySamlSubmitError,
   buildSamlConfigurationPayload,
@@ -39,9 +38,9 @@ import {
   type IdpConfigurationMode,
 } from './shared/IdentityProviderConfigurationModes';
 
-export const SamlMicrosoftConfigureSteps = ({ onComplete }: ProviderConfigureStepsProps): JSX.Element => {
+export const SamlMicrosoftConfigureSteps = (): JSX.Element => {
   return (
-    <Wizard onComplete={onComplete}>
+    <Wizard>
       <Wizard.Step id='create-app'>
         <Step.Header
           title={localizationKeys('configureSSO.configureStep.samlMicrosoft.mainHeaderTitle')}