feat: add destination-labeled back button to Employee OnboardingExecutionFlow

.reports/embedded-react-sdk.api.md

@@ -930,6 +930,7 @@ export const componentEvents: {
     readonly EMPLOYEE_DELETED: "employee/deleted";
     readonly EMPLOYEE_DISMISS: "employee/dismiss";
     readonly EMPLOYEE_ONBOARDING_DONE: "employee/onboarding/done";
+    readonly EMPLOYEE_ONBOARDING_BACK: "employee/onboarding/back";
     readonly EMPLOYEE_PROFILE_DONE: "employee/profile/done";
     readonly EMPLOYEE_HOME_ADDRESS_CREATED: "employee/addresses/home/created";
     readonly EMPLOYEE_HOME_ADDRESS_UPDATED: "employee/addresses/home/updated";
@@ -3333,6 +3334,8 @@ function OnboardingExecutionFlow(input: OnboardingExecutionFlowProps): JSX;
 interface OnboardingExecutionFlowProps {
     companyId: string;
     defaultValues?: OnboardingDefaultValues;
+    // Warning: (ae-forgotten-export) The symbol "FlowHeaderConfig" needs to be exported by the entry point index.d.ts
+    initialBackHeader?: FlowHeaderConfig;
     initialEmployeeId?: string;
     initialOnboardingStatus?: (typeof EmployeeOnboardingStatus)[keyof typeof EmployeeOnboardingStatus];
     initialState?: OnboardingExecutionInitialState;

docs/api/events.md

@@ -184,6 +184,7 @@ Catalog of every event key that an SDK component can emit through `onEvent`.
 | `EMPLOYEE_MANAGEMENT_WORK_ADDRESS_EDIT_CANCELLED` | `"employee/management/workAddress/editCancelled"` | `'employee/management/workAddress/editCancelled'` |
 | `EMPLOYEE_MANAGEMENT_WORK_ADDRESS_EDIT_REQUESTED` | `"employee/management/workAddress/editRequested"` | `'employee/management/workAddress/editRequested'` |
 | `EMPLOYEE_MANAGEMENT_WORK_ADDRESS_UPDATED` | `"employee/management/workAddress/updated"` | `'employee/management/workAddress/updated'` |
+| `EMPLOYEE_ONBOARDING_BACK` | `"employee/onboarding/back"` | `'employee/onboarding/back'` |
 | `EMPLOYEE_ONBOARDING_DOCUMENTS_CONFIG_UPDATED` | `"employee/onboardingDocumentsConfig/updated"` | `'employee/onboardingDocumentsConfig/updated'` |
 | `EMPLOYEE_ONBOARDING_DONE` | `"employee/onboarding/done"` | `'employee/onboarding/done'` |
 | `EMPLOYEE_ONBOARDING_STATUS_UPDATED` | `"employee/onboardingStatus/updated"` | `'employee/onboardingStatus/updated'` |

src/components/Company/OnboardingFlow/onboardingStateMachine.ts

@@ -18,7 +18,7 @@ import type { FlowHeaderConfig } from '@/components/Flow/useFlow'
 const TOTAL_STEPS = 8
 
 const progressHeader = (currentStep: number): FlowHeaderConfig => ({
-  type: 'progress',
+  indicator: 'progress',
   currentStep,
   totalSteps: TOTAL_STEPS,
 })

src/components/Contractor/OnboardingFlow/onboardingStateMachine.ts

@@ -28,7 +28,7 @@ const progressHeader = (
   currentStep: number,
   totalSteps: number = TOTAL_STEPS_DEFAULT,
 ): FlowHeaderConfig => ({
-  type: 'progress',
+  indicator: 'progress',
   currentStep,
   totalSteps,
   cta: ProgressBarCta,

src/components/Contractor/Payments/PaymentFlow/PaymentFlow.tsx

@@ -17,7 +17,7 @@ export const PaymentFlow = ({ companyId, onEvent }: PaymentFlowProps) => {
         component: PaymentListContextual,
         companyId,
         header: {
-          type: 'breadcrumbs' as const,
+          indicator: 'breadcrumbs' as const,
           breadcrumbs: buildBreadcrumbs(paymentFlowBreadcrumbsNodes),
         },
       })),

src/components/Employee/EmployeeListFlow/employeeListStateMachine.ts

@@ -16,7 +16,7 @@ type EventPayloads = {
 }
 
 const backToListHeader: FlowHeaderConfig = {
-  type: 'minimal',
+  indicator: 'none',
   back: {
     labelKey: 'backToListCta',
     namespace: 'Employee.ManagementEmployeeList',

src/components/Employee/OnboardingExecutionFlow/OnboardingExecutionFlow.tsx

@@ -3,6 +3,7 @@ import { useMemo } from 'react'
 import {
   onboardingExecutionMachine,
   INITIAL_COMPONENT_MAP,
+  stepHeader,
   type OnboardingExecutionInitialState,
 } from './onboardingExecutionStateMachine'
 import {
@@ -12,6 +13,8 @@ import {
 import { Flow } from '@/components/Flow/Flow'
 import type { OnEventType } from '@/components/Base/useBase'
 import type { EventType, EmployeeOnboardingStatus } from '@/shared/constants'
+import type { FlowHeaderConfig } from '@/components/Flow/useFlow'
+import { useI18n } from '@/i18n'
 
 /**
  * Props for {@link OnboardingExecutionFlow}.
@@ -37,6 +40,14 @@ export interface OnboardingExecutionFlowProps {
   isSelfOnboardingEnabled?: boolean
   /** When true, enables the Employee Documents step in the flow, allowing the admin to configure I-9 document requirements. Defaults to `false`. */
   withEmployeeI9?: boolean
+  /**
+   * Optional header shown above the initial step. Only the `back` affordance
+   * is read — the indicator is always the execution-flow progress bar. The
+   * back affordance is preserved if the user navigates back to step one from
+   * a later step. Use this to expose an "exit" path when the flow is rendered
+   * inside a parent flow (e.g. back to an employee list).
+   */
+  initialBackHeader?: FlowHeaderConfig
 }
 
 /**
@@ -78,23 +89,33 @@ export function OnboardingExecutionFlow({
   isAdmin = true,
   isSelfOnboardingEnabled = true,
   withEmployeeI9 = false,
+  initialBackHeader,
 }: OnboardingExecutionFlowProps) {
+  useI18n('Employee.OnboardingExecutionFlow')
   const machine = useMemo(
     () =>
       createMachine(
         initialState,
         onboardingExecutionMachine,
-        (initialContext: OnboardingContextInterface) => ({
-          ...initialContext,
-          component: INITIAL_COMPONENT_MAP[initialState],
-          companyId,
-          employeeId: initialEmployeeId,
-          onboardingStatus: initialOnboardingStatus,
-          defaultValues,
-          isAdmin,
-          isSelfOnboardingEnabled,
-          withEmployeeI9,
-        }),
+        (initialContext: OnboardingContextInterface) => {
+          const initialBack = initialBackHeader?.back ?? null
+          const baseContext: OnboardingContextInterface = {
+            ...initialContext,
+            component: INITIAL_COMPONENT_MAP[initialState],
+            companyId,
+            employeeId: initialEmployeeId,
+            onboardingStatus: initialOnboardingStatus,
+            defaultValues,
+            isAdmin,
+            isSelfOnboardingEnabled,
+            withEmployeeI9,
+            initialBack,
+          }
+          return {
+            ...baseContext,
+            header: stepHeader(baseContext, initialState, initialBack),
+          }
+        },
       ),
     [
       companyId,
@@ -105,6 +126,7 @@ export function OnboardingExecutionFlow({
       isAdmin,
       isSelfOnboardingEnabled,
       withEmployeeI9,
+      initialBackHeader,
     ],
   )
 

src/components/Employee/OnboardingExecutionFlow/OnboardingExecutionFlowComponents.tsx

@@ -5,7 +5,7 @@ import { StateTaxes } from '../StateTaxes/onboarding/StateTaxes'
 import type { ProfileDefaultValues } from '../Profile/onboarding/Profile'
 import type { CompensationDefaultValues } from '../Compensation'
 import { ensureRequired } from '@/helpers/ensureRequired'
-import { useFlow, type FlowContextInterface } from '@/components/Flow/useFlow'
+import { useFlow, type BackConfig, type FlowContextInterface } from '@/components/Flow/useFlow'
 import type { EmployeeOnboardingStatus } from '@/shared/constants'
 import type { RequireAtLeastOne } from '@/types/Helpers'
 
@@ -38,6 +38,10 @@ export interface OnboardingContextInterface extends FlowContextInterface {
   defaultValues?: OnboardingDefaultValues
   isSelfOnboardingEnabled?: boolean
   withEmployeeI9?: boolean
+  // Back affordance to render on the initial step (and restored when the user
+  // navigates back to it). Lets a parent flow expose an "exit" affordance from
+  // step one without changing the back behaviour of intermediate steps.
+  initialBack?: BackConfig | null
 }
 
 /** @internal */