feat(SDK-1129): add HistoricalPaymentsFlow #2552
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,160 @@ | ||
| import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' | ||
| import { screen, waitFor, within } from '@testing-library/react' | ||
| import userEvent from '@testing-library/user-event' | ||
| import { HttpResponse } from 'msw' | ||
| import { HistoricalPaymentFlow } from './HistoricalPaymentFlow' | ||
| import { server } from '@/test/mocks/server' | ||
| import { renderWithProviders } from '@/test-utils/renderWithProviders' | ||
| import { handleGetContractorsList } from '@/test/mocks/apis/contractors' | ||
| import { | ||
| handleCreateContractorPaymentGroup, | ||
| handleGetContractorPaymentGroup, | ||
| handlePreviewContractorPaymentGroup, | ||
| } from '@/test/mocks/apis/contractor_payment_groups' | ||
| import { componentEvents } from '@/shared/constants' | ||
|
|
||
| const COMPANY_ID = 'company-123' | ||
| const DATE_LABEL = 'Payment date' | ||
|
|
||
| const hourlyContractor = { | ||
| uuid: 'contractor-1', | ||
| company_uuid: COMPANY_ID, | ||
| wage_type: 'Hourly', | ||
| type: 'Individual', | ||
| first_name: 'Ada', | ||
| last_name: 'Lovelace', | ||
| is_active: true, | ||
| onboarding_status: 'onboarding_completed', | ||
| hourly_rate: '50.00', | ||
| payment_method: 'Direct Deposit', | ||
| } | ||
|
|
||
| const createdPaymentGroup = { | ||
| uuid: 'created-group-uuid', | ||
| company_uuid: COMPANY_ID, | ||
| check_date: '2026-07-15', | ||
| status: 'Funded', | ||
| totals: { amount: '500.00' }, | ||
| contractor_payments: [ | ||
| { | ||
| uuid: 'payment-1', | ||
| contractor_uuid: 'contractor-1', | ||
| payment_method: 'Historical Payment', | ||
| wage_type: 'Hourly', | ||
| hourly_rate: '50.00', | ||
| hours: '10', | ||
| bonus: '0', | ||
| reimbursement: '0', | ||
| wage_total: '500.00', | ||
| }, | ||
| ], | ||
| } | ||
|
|
||
| const renderScreen = (onEvent = vi.fn()) => { | ||
| server.use( | ||
| handleGetContractorsList(() => | ||
| HttpResponse.json([hourlyContractor], { | ||
| headers: { 'x-total-pages': '1', 'x-total-count': '1' }, | ||
| }), | ||
| ), | ||
| handlePreviewContractorPaymentGroup(() => | ||
| HttpResponse.json({ | ||
| check_date: '2026-07-15', | ||
| creation_token: 'preview-token-123', | ||
| contractor_payments: [ | ||
| { | ||
| contractor_uuid: 'contractor-1', | ||
| uuid: 'preview-payment-1', | ||
| wage_type: 'Hourly', | ||
| hourly_rate: '50.00', | ||
| hours: '10', | ||
| wage_total: '500.00', | ||
| }, | ||
| ], | ||
| totals: { amount: '500.00' }, | ||
| }), | ||
| ), | ||
| handleCreateContractorPaymentGroup(() => | ||
| HttpResponse.json(createdPaymentGroup, { status: 201 }), | ||
| ), | ||
| handleGetContractorPaymentGroup(() => HttpResponse.json(createdPaymentGroup)), | ||
| ) | ||
| renderWithProviders(<HistoricalPaymentFlow companyId={COMPANY_ID} onEvent={onEvent} />) | ||
| return { onEvent } | ||
| } | ||
|
|
||
| async function typeDate( | ||
| user: ReturnType<typeof userEvent.setup>, | ||
| { month, day, year }: { month: string; day: string; year: string }, | ||
| ) { | ||
| const group = screen.getByRole('group', { name: new RegExp(DATE_LABEL, 'i') }) | ||
| await user.type(within(group).getByRole('spinbutton', { name: /^month/i }), month) | ||
| await user.type(within(group).getByRole('spinbutton', { name: /^day/i }), day) | ||
| await user.type(within(group).getByRole('spinbutton', { name: /^year/i }), year) | ||
| } | ||
|
|
||
| const walkToSummary = async (user: ReturnType<typeof userEvent.setup>) => { | ||
| await waitFor(() => { | ||
| expect(screen.getByText('Ada Lovelace')).toBeInTheDocument() | ||
| }) | ||
| await typeDate(user, { month: '07', day: '15', year: '2026' }) | ||
| const checkboxes = screen.getAllByRole('checkbox') | ||
| await user.click(checkboxes[1] as Element) | ||
| await waitFor(() => { | ||
| expect(screen.getByRole('button', { name: 'Continue' })).toBeEnabled() | ||
| }) | ||
| await user.click(screen.getByRole('button', { name: 'Continue' })) | ||
|
|
||
| await screen.findByRole('heading', { name: 'Enter payment amounts' }) | ||
| await user.click(screen.getByRole('button', { name: 'Edit contractor payment' })) | ||
| await user.click(await screen.findByRole('menuitem', { name: 'Edit contractor payment' })) | ||
| await user.type(screen.getByLabelText('Hours'), '10') | ||
| await user.click(screen.getByRole('button', { name: 'Done' })) | ||
|
|
||
| await waitFor(() => { | ||
| expect(screen.getByRole('button', { name: 'Continue' })).toBeEnabled() | ||
| }) | ||
| await user.click(screen.getByRole('button', { name: 'Continue' })) | ||
|
|
||
| await screen.findByRole('heading', { name: 'Review and submit' }) | ||
| await user.click(screen.getByRole('button', { name: 'Submit historical payment' })) | ||
| } | ||
|
|
||
| describe('HistoricalPaymentFlow', () => { | ||
| let user: ReturnType<typeof userEvent.setup> | ||
|
|
||
| beforeEach(() => { | ||
| vi.useFakeTimers({ shouldAdvanceTime: true }) | ||
| vi.setSystemTime(new Date('2026-07-27T12:00:00-07:00')) | ||
| user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime }) | ||
| }) | ||
|
|
||
| afterEach(() => { | ||
| vi.useRealTimers() | ||
| }) | ||
|
|
||
| it('chains CreateHistoricalPayment into HistoricalPaymentSummary, carrying the created payment group id', async () => { | ||
| const { onEvent } = renderScreen() | ||
|
|
||
| await walkToSummary(user) | ||
|
|
||
| expect(await screen.findByRole('heading', { name: 'Payment summary' })).toBeInTheDocument() | ||
| expect(screen.getByText('Ada Lovelace')).toBeInTheDocument() | ||
|
Check failure on line 142 in src/components/Contractor/Payments/HistoricalPaymentFlow/HistoricalPaymentFlow.test.tsx
|
||
| expect(onEvent).toHaveBeenCalledWith( | ||
| componentEvents.CONTRACTOR_HISTORICAL_PAYMENT_CREATED, | ||
| expect.objectContaining({ uuid: 'created-group-uuid' }), | ||
| ) | ||
| }) | ||
|
|
||
| it('emits exit when Done is clicked on the summary', async () => { | ||
| const { onEvent } = renderScreen() | ||
|
|
||
| await walkToSummary(user) | ||
| await user.click(await screen.findByRole('button', { name: 'Done' })) | ||
|
|
||
| expect(onEvent).toHaveBeenCalledWith( | ||
| componentEvents.CONTRACTOR_HISTORICAL_PAYMENT_EXIT, | ||
| undefined, | ||
| ) | ||
| }) | ||
| }) | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,126 @@ | ||
| import { createMachine } from 'robot3' | ||
| import { useState } from 'react' | ||
| import { | ||
| historicalPaymentBreadcrumbsNodes, | ||
| historicalPaymentMachine, | ||
| } from './historicalPaymentMachine' | ||
| import { | ||
| CreateHistoricalPaymentContextual, | ||
| type HistoricalPaymentFlowContextInterface, | ||
| type HistoricalPaymentFlowProps, | ||
| } from './HistoricalPaymentFlowComponents' | ||
| import { Flow } from '@/components/Flow/Flow' | ||
| import type { FlowBreadcrumb } from '@/components/Common/FlowBreadcrumbs/FlowBreadcrumbsTypes' | ||
| import { buildBreadcrumbs, updateBreadcrumbs } from '@/helpers/breadcrumbHelpers' | ||
|
|
||
| const EMPTY_BREADCRUMBS: FlowBreadcrumb[] = [] | ||
|
|
||
| /** | ||
| * Props for the flow-internal {@link HistoricalPaymentInternalFlow}, which layers a parent flow's | ||
| * prefix breadcrumbs on top of the public {@link HistoricalPaymentFlowProps}. | ||
| * | ||
| * @internal | ||
| */ | ||
| export interface HistoricalPaymentInternalFlowProps extends HistoricalPaymentFlowProps { | ||
| /** | ||
| * Breadcrumbs prepended to the flow's own breadcrumb trail. Set by a parent flow (e.g. | ||
| * `PaymentFlow`) so the breadcrumb history remains coherent across the handoff. | ||
| */ | ||
| prefixBreadcrumbs?: FlowBreadcrumb[] | ||
| } | ||
|
|
||
| /** | ||
| * Guided flow to record a historical contractor payment and review the resulting summary. | ||
| * | ||
| * @remarks | ||
| * This is the inner flow that powers the historical-payment spoke of `ContractorManagement.PaymentFlow`. | ||
| * Render it directly when you have built your own payments landing page and want to hand the user | ||
| * off to the standard historical-payment experience without re-implementing it. A historical payment | ||
| * already happened outside Gusto and does not move money, so unlike `CreatePaymentFlow` there is no | ||
| * Fast ACH blocker or wire-transfer step. | ||
| * | ||
| * @events | ||
| * | Event | Description | Data | | ||
| * | ----- | ----------- | ---- | | ||
| * | `contractor/historicalPayments/edit` | The edit modal was opened for a contractor | — | | ||
| * | `contractor/historicalPayments/update` | A contractor's payment values were updated locally | The updated form values (hours, wage, bonus, reimbursement, payment method, etc.) | | ||
| * | `contractor/historicalPayments/preview` | The preview API call succeeded | The contractor payment group preview response | | ||
| * | `contractor/historicalPayments/backToEdit` | The user returned from preview to continue editing | — | | ||
| * | `contractor/historicalPayments/created` | The payment group was successfully created | The created `ContractorPaymentGroup` | | ||
| * | `contractor/historicalPayments/exit` | User is done reviewing the summary | — | | ||
| * | `breadcrumb/navigate` | Fired when the user clicks a breadcrumb to navigate back | `{ key: string, onNavigate: (ctx) => ctx }` | | ||
| * | ||
| * @components | ||
| * - {@link CreateHistoricalPayment} | ||
| * - {@link HistoricalPaymentSummary} | ||
| * | ||
| * @param props - See {@link HistoricalPaymentFlowProps}. | ||
| * @returns The composed historical-payment flow. | ||
| * @alpha | ||
| * | ||
| * @example | ||
| * ```tsx title="App.tsx" | ||
| * import { ContractorManagement } from '@gusto/embedded-react-sdk' | ||
| * | ||
| * function MyApp() { | ||
| * return ( | ||
| * <ContractorManagement.HistoricalPaymentFlow | ||
| * companyId="a007e1ab-3595-43c2-ab4b-af7a5af2e365" | ||
| * onEvent={() => {}} | ||
| * /> | ||
| * ) | ||
| * } | ||
| * ``` | ||
| */ | ||
| export function HistoricalPaymentFlow(props: HistoricalPaymentFlowProps) { | ||
| return <HistoricalPaymentInternalFlow {...props} /> | ||
| } | ||
|
|
||
| /** | ||
| * Flow-internal entry point for {@link HistoricalPaymentFlow} that additionally accepts | ||
| * flow-injected `prefixBreadcrumbs`. Partners use {@link HistoricalPaymentFlow}; `PaymentFlow` | ||
| * renders this directly to prepend its own breadcrumb trail. | ||
| * | ||
| * @internal | ||
| */ | ||
| export function HistoricalPaymentInternalFlow({ | ||
| companyId, | ||
| onEvent, | ||
| prefixBreadcrumbs = EMPTY_BREADCRUMBS, | ||
| }: HistoricalPaymentInternalFlowProps) { | ||
| // Built once via a lazy useState initializer, not useMemo: the machine's identity must survive | ||
| // re-renders no matter what, and useMemo is only a performance hint React may discard, not an | ||
| // identity guarantee. A useMemo keyed on `prefixBreadcrumbs` would recreate this machine (and | ||
| // reset in-flight state, losing entered amounts) whenever the parent app re-renders in response | ||
| // to a bubbled `onEvent` call, since an inline array literal upstream gets a new reference every | ||
| // render. | ||
| const [historicalPaymentFlow] = useState(() => { | ||
| const baseBreadcrumbs = buildBreadcrumbs(historicalPaymentBreadcrumbsNodes) | ||
| const breadcrumbs = Object.fromEntries( | ||
| Object.entries(baseBreadcrumbs).map(([stateKey, trail]) => [ | ||
| stateKey, | ||
| [...prefixBreadcrumbs, ...trail], | ||
| ]), | ||
| ) | ||
|
|
||
| const initialBreadcrumbContext = updateBreadcrumbs('createHistoricalPayment', { | ||
| header: { | ||
| type: 'breadcrumbs' as const, | ||
| breadcrumbs, | ||
| }, | ||
| }) | ||
|
|
||
| return createMachine( | ||
| 'createHistoricalPayment', | ||
| historicalPaymentMachine, | ||
| (initialContext: HistoricalPaymentFlowContextInterface) => ({ | ||
| ...initialContext, | ||
| ...initialBreadcrumbContext, | ||
| component: CreateHistoricalPaymentContextual, | ||
| companyId, | ||
| }), | ||
| ) | ||
| }) | ||
|
|
||
| return <Flow machine={historicalPaymentFlow} onEvent={onEvent} /> | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,41 @@ | ||
| import { CreateHistoricalPayment } from '../CreateHistoricalPayment/CreateHistoricalPayment' | ||
| import { HistoricalPaymentSummary } from '../HistoricalPaymentSummary/HistoricalPaymentSummary' | ||
| import { useFlow, type FlowContextInterface } from '@/components/Flow/useFlow' | ||
| import type { BaseComponentInterface } from '@/components/Base' | ||
| import { ensureRequired } from '@/helpers/ensureRequired' | ||
|
|
||
| /** | ||
| * Props for {@link HistoricalPaymentFlow}. | ||
| * | ||
| * @alpha | ||
| */ | ||
| export interface HistoricalPaymentFlowProps extends BaseComponentInterface<never> { | ||
| /** The associated company identifier. */ | ||
| companyId: string | ||
| } | ||
|
|
||
| /** @internal */ | ||
| export interface HistoricalPaymentFlowContextInterface extends FlowContextInterface { | ||
| companyId: string | ||
| createdPaymentGroupId?: string | ||
| } | ||
|
|
||
| /** @internal */ | ||
| export function CreateHistoricalPaymentContextual() { | ||
| const { companyId, onEvent } = useFlow<HistoricalPaymentFlowContextInterface>() | ||
| return <CreateHistoricalPayment onEvent={onEvent} companyId={ensureRequired(companyId)} /> | ||
| } | ||
|
|
||
| /** @internal */ | ||
| export function HistoricalPaymentSummaryContextual() { | ||
| const { createdPaymentGroupId, companyId, onEvent } = | ||
| useFlow<HistoricalPaymentFlowContextInterface>() | ||
|
|
||
| return ( | ||
| <HistoricalPaymentSummary | ||
| onEvent={onEvent} | ||
| paymentGroupId={ensureRequired(createdPaymentGroupId)} | ||
| companyId={ensureRequired(companyId)} | ||
| /> | ||
| ) | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You might consider placing the machine creation in a useMemo here instead. Ex. if we got a new company id, we'd want to tear down the machine and create a new one