feat(SDK-1161): add PrintChecksBanner

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

@@ -1293,6 +1293,13 @@ export const componentEvents: {
     readonly CONTRACTOR_PAYMENT_CANCEL: "contractor/payments/cancel";
     readonly CONTRACTOR_PAYMENT_EXIT: "contractor/payments/exit";
     readonly CONTRACTOR_PAYMENT_RFI_RESPOND: "contractor/payments/rfi/respond";
+    readonly PRINT_CHECKS_START: "payroll/printChecks/start";
+    readonly PRINT_CHECKS_GENERATE_START: "payroll/printChecks/generate/start";
+    readonly PRINT_CHECKS_GENERATE_SUCCEEDED: "payroll/printChecks/generate/succeeded";
+    readonly PRINT_CHECKS_GENERATE_FAILED: "payroll/printChecks/generate/failed";
+    readonly PRINT_CHECKS_RETRY: "payroll/printChecks/retry";
+    readonly PRINT_CHECKS_CANCEL: "payroll/printChecks/cancel";
+    readonly PRINT_CHECKS_CLOSE: "payroll/printChecks/close";
     readonly RECOVERY_CASE_RESOLVE: "recoveryCase/resolve";
     readonly RECOVERY_CASE_RESUBMIT: "recoveryCase/resubmit";
     readonly RECOVERY_CASE_RESUBMIT_CANCEL: "recoveryCase/resubmit/cancel";
@@ -4993,6 +5000,12 @@ export interface Resources {
     // (undocumented)
     'Payroll.PayrollReceipts': Translations.PayrollPayrollReceipts
     // (undocumented)
+    'Payroll.PrintChecksBanner': Translations.PayrollPrintChecksBanner
+    // (undocumented)
+    'Payroll.PrintChecksFailure': Translations.PayrollPrintChecksFailure
+    // (undocumented)
+    'Payroll.PrintChecksSummary': Translations.PayrollPrintChecksSummary
+    // (undocumented)
     'Payroll.RecoveryCasesList': Translations.PayrollRecoveryCasesList
     // (undocumented)
     'Payroll.RecoveryCasesResubmit': Translations.PayrollRecoveryCasesResubmit

docs/reference/Translations/index.md

@@ -5234,6 +5234,56 @@ Translation keys for the `Payroll.PayrollReceipts` i18n namespace.
 
 ***
 
+<a id="payrollprintchecksbanner"></a>
+
+### PayrollPrintChecksBanner
+
+Translation keys for the `Payroll.PrintChecksBanner` i18n namespace.
+
+#### Properties
+
+| Property | Default value |
+| ------ | ------ |
+| <a id="property-payrollprintchecksbannercta"></a> `cta` | `"View and print checks"` |
+| <a id="property-payrollprintchecksbannerdescription"></a> `description` | `"Employees with this payment method will need their checks delivered to them. If you aren't using your own checks, you can view and print checks."` |
+| <a id="property-payrollprintchecksbannertitle_one"></a> `title_one` | `"You noted {{count}} employee that should be paid by check."` |
+| <a id="property-payrollprintchecksbannertitle_other"></a> `title_other` | `"You noted {{count}} employees that should be paid by check."` |
+
+***
+
+<a id="payrollprintchecksfailure"></a>
+
+### PayrollPrintChecksFailure
+
+Translation keys for the `Payroll.PrintChecksFailure` i18n namespace.
+
+#### Properties
+
+| Property | Default value |
+| ------ | ------ |
+| <a id="property-payrollprintchecksfailureclosecta"></a> `closeCta` | `"Close"` |
+| <a id="property-payrollprintchecksfailurefailedtitle"></a> `failedTitle` | `"We couldn't generate your checks"` |
+| <a id="property-payrollprintchecksfailureretrycta"></a> `retryCta` | `"Try again"` |
+
+***
+
+<a id="payrollprintcheckssummary"></a>
+
+### PayrollPrintChecksSummary
+
+Translation keys for the `Payroll.PrintChecksSummary` i18n namespace.
+
+#### Properties
+
+| Property | Default value |
+| ------ | ------ |
+| <a id="property-payrollprintcheckssummaryclosecta"></a> `closeCta` | `"Close"` |
+| <a id="property-payrollprintcheckssummarysucceededdescription"></a> `succeededDescription` | `"The download should have started automatically. If not, use the link below."` |
+| <a id="property-payrollprintcheckssummarysucceededtitle"></a> `succeededTitle` | `"Your checks are ready"` |
+| <a id="property-payrollprintcheckssummaryviewcheckscta"></a> `viewChecksCta` | `"View checks"` |
+
+***
+
 <a id="payrollrecoverycaseslist"></a>
 
 ### PayrollRecoveryCasesList
@@ -5606,6 +5656,9 @@ yields that namespace's keys. Backs i18next `t()` typing and `ResourceDictionary
 | <a id="property-resourcespayrollpayrolllist"></a> `Payroll.PayrollList` | [`PayrollPayrollList`](#payrollpayrolllist) |
 | <a id="property-resourcespayrollpayrolloverview"></a> `Payroll.PayrollOverview` | [`PayrollPayrollOverview`](#payrollpayrolloverview) |
 | <a id="property-resourcespayrollpayrollreceipts"></a> `Payroll.PayrollReceipts` | [`PayrollPayrollReceipts`](#payrollpayrollreceipts) |
+| <a id="property-resourcespayrollprintchecksbanner"></a> `Payroll.PrintChecksBanner` | [`PayrollPrintChecksBanner`](#payrollprintchecksbanner) |
+| <a id="property-resourcespayrollprintchecksfailure"></a> `Payroll.PrintChecksFailure` | [`PayrollPrintChecksFailure`](#payrollprintchecksfailure) |
+| <a id="property-resourcespayrollprintcheckssummary"></a> `Payroll.PrintChecksSummary` | [`PayrollPrintChecksSummary`](#payrollprintcheckssummary) |
 | <a id="property-resourcespayrollrecoverycaseslist"></a> `Payroll.RecoveryCasesList` | [`PayrollRecoveryCasesList`](#payrollrecoverycaseslist) |
 | <a id="property-resourcespayrollrecoverycasesresubmit"></a> `Payroll.RecoveryCasesResubmit` | [`PayrollRecoveryCasesResubmit`](#payrollrecoverycasesresubmit) |
 | <a id="property-resourcespayrolltransition"></a> `Payroll.Transition` | [`PayrollTransition`](#payrolltransition) |

docs/reference/events.md

@@ -304,6 +304,13 @@ import { componentEvents, EmployeeOnboarding } from '@gusto/embedded-react-sdk'
 | `PAYROLL_WIRE_INSTRUCTIONS_DONE` | `"payroll/wire/instructions/done"` |
 | `PAYROLL_WIRE_INSTRUCTIONS_SELECT` | `"payroll/wire/instructions/select"` |
 | `PAYROLL_WIRE_START_TRANSFER` | `"payroll/wire/startTransfer"` |
+| `PRINT_CHECKS_CANCEL` | `"payroll/printChecks/cancel"` |
+| `PRINT_CHECKS_CLOSE` | `"payroll/printChecks/close"` |
+| `PRINT_CHECKS_GENERATE_FAILED` | `"payroll/printChecks/generate/failed"` |
+| `PRINT_CHECKS_GENERATE_START` | `"payroll/printChecks/generate/start"` |
+| `PRINT_CHECKS_GENERATE_SUCCEEDED` | `"payroll/printChecks/generate/succeeded"` |
+| `PRINT_CHECKS_RETRY` | `"payroll/printChecks/retry"` |
+| `PRINT_CHECKS_START` | `"payroll/printChecks/start"` |
 | `RECOVERY_CASE_RESOLVE` | `"recoveryCase/resolve"` |
 | `RECOVERY_CASE_RESUBMIT` | `"recoveryCase/resubmit"` |
 | `RECOVERY_CASE_RESUBMIT_CANCEL` | `"recoveryCase/resubmit/cancel"` |

src/components/Payroll/PrintChecks/PrintChecksBanner/PrintChecksBanner.test.tsx

@@ -0,0 +1,91 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { PrintChecksBanner } from './PrintChecksBanner'
+import { renderWithProviders } from '@/test-utils/renderWithProviders'
+
+const checkCompensation = {
+  employeeUuid: 'emp-check-1',
+  excluded: false,
+  paymentMethod: 'Check',
+}
+
+let mockEmployeeCompensations: Record<string, unknown>[] = []
+let mockProcessed = false
+let mockProcessingStatus: string | undefined
+
+vi.mock('@gusto/embedded-api/react-query/payrollsGet', () => ({
+  usePayrollsGet: () => ({
+    data: {
+      payrollShow: {
+        processed: mockProcessed,
+        processingRequest: mockProcessingStatus ? { status: mockProcessingStatus } : undefined,
+        employeeCompensations: mockEmployeeCompensations,
+      },
+    },
+  }),
+}))
+
+describe('PrintChecksBanner', () => {
+  const onEvent = vi.fn()
+  const onStartPrintChecks = vi.fn()
+  const user = userEvent.setup()
+
+  const defaultProps = {
+    companyId: 'company-1',
+    payrollId: 'payroll-1',
+    onStartPrintChecks,
+    onEvent,
+  }
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    mockEmployeeCompensations = []
+    mockProcessed = false
+    mockProcessingStatus = undefined
+  })
+
+  it('renders nothing when no employees are paid by check', () => {
+    renderWithProviders(<PrintChecksBanner {...defaultProps} />)
+
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+
+  it('shows the alert without a CTA when the payroll has not been processed', async () => {
+    mockEmployeeCompensations = [checkCompensation]
+
+    renderWithProviders(<PrintChecksBanner {...defaultProps} />)
+
+    expect(await screen.findByText(/noted 1 employee/i)).toBeInTheDocument()
+    expect(screen.queryByRole('button', { name: 'View and print checks' })).toBeNull()
+  })
+
+  it('shows the CTA once the payroll is processed, and fires onStartPrintChecks when clicked', async () => {
+    mockEmployeeCompensations = [checkCompensation]
+    mockProcessed = true
+
+    renderWithProviders(<PrintChecksBanner {...defaultProps} />)
+
+    const cta = await screen.findByRole('button', { name: 'View and print checks' })
+    await user.click(cta)
+
+    expect(onStartPrintChecks).toHaveBeenCalledTimes(1)
+  })
+
+  it('shows the CTA when the processing request succeeded even if processed is not yet true', async () => {
+    mockEmployeeCompensations = [checkCompensation]
+    mockProcessingStatus = 'submit_success'
+
+    renderWithProviders(<PrintChecksBanner {...defaultProps} />)
+
+    expect(await screen.findByRole('button', { name: 'View and print checks' })).toBeInTheDocument()
+  })
+
+  it('excludes compensations marked as excluded from the count', () => {
+    mockEmployeeCompensations = [{ ...checkCompensation, excluded: true }]
+
+    renderWithProviders(<PrintChecksBanner {...defaultProps} />)
+
+    expect(screen.queryByRole('alert')).toBeNull()
+  })
+})

src/components/Payroll/PrintChecks/PrintChecksBanner/PrintChecksBanner.tsx

@@ -0,0 +1,65 @@
+import { useTranslation } from 'react-i18next'
+import { usePayrollsGet } from '@gusto/embedded-api/react-query/payrollsGet'
+import { BaseComponent, type BaseComponentInterface } from '@/components/Base'
+import { useComponentContext } from '@/contexts/ComponentAdapter/useComponentContext'
+import { useComponentDictionary, useI18n } from '@/i18n'
+import { PAYMENT_METHODS, PAYROLL_PROCESSING_STATUS } from '@/shared/constants'
+
+interface PrintChecksBannerProps extends BaseComponentInterface<'Payroll.PrintChecksBanner'> {
+  companyId: string
+  payrollId: string
+  onStartPrintChecks: () => void
+}
+
+/** @internal */
+export function PrintChecksBanner(props: PrintChecksBannerProps) {
+  return (
+    <BaseComponent {...props}>
+      <Root {...props}>{props.children}</Root>
+    </BaseComponent>
+  )
+}
+
+const Root = ({ companyId, payrollId, dictionary, onStartPrintChecks }: PrintChecksBannerProps) => {
+  useComponentDictionary('Payroll.PrintChecksBanner', dictionary)
+  useI18n('Payroll.PrintChecksBanner')
+  const { t } = useTranslation('Payroll.PrintChecksBanner')
+  const { Alert, Button } = useComponentContext()
+
+  const { data } = usePayrollsGet({
+    companyId,
+    payrollId,
+  })
+  const payrollData = data?.payrollShow
+
+  const checkPaymentsCount =
+    payrollData?.employeeCompensations?.reduce(
+      (acc, comp) =>
+        !comp.excluded && comp.paymentMethod === PAYMENT_METHODS.check ? acc + 1 : acc,
+      0,
+    ) ?? 0
+
+  const isProcessed =
+    payrollData?.processed === true ||
+    payrollData?.processingRequest?.status === PAYROLL_PROCESSING_STATUS.submit_success
+
+  if (checkPaymentsCount === 0) {
+    return null
+  }
+
+  return (
+    <Alert
+      status="info"
+      label={t('title', { count: checkPaymentsCount })}
+      action={
+        isProcessed && (
+          <Button variant="secondary" onClick={onStartPrintChecks}>
+            {t('cta')}
+          </Button>
+        )
+      }
+    >
+      {t('description')}
+    </Alert>
+  )
+}

src/components/Payroll/PrintChecks/PrintChecksBanner/index.ts

@@ -0,0 +1 @@
+export { PrintChecksBanner } from './PrintChecksBanner'

src/components/Payroll/PrintChecks/PrintChecksFailure/PrintChecksFailure.stories.tsx

@@ -0,0 +1,35 @@
+import { Suspense } from 'react'
+import { fn } from 'storybook/test'
+import { MockBaseProvider } from '../../../../../.storybook/helpers/MockBaseProvider'
+import { PrintChecksFailure } from './PrintChecksFailure'
+import { useI18n } from '@/i18n'
+
+function I18nLoader({ children }: { children: React.ReactNode }) {
+  useI18n('Payroll.PrintChecksFailure')
+  return <>{children}</>
+}
+
+export default {
+  title: 'Domain/Payroll/PrintChecksFailure',
+  decorators: [
+    (Story: React.ComponentType) => (
+      <Suspense fallback={<div>Loading translations...</div>}>
+        <I18nLoader>
+          <MockBaseProvider>
+            <Story />
+          </MockBaseProvider>
+        </I18nLoader>
+      </Suspense>
+    ),
+  ],
+}
+
+export const Default = () => (
+  <>
+    <PrintChecksFailure
+      errorMessage="Cannot generate checks on an unprocessed payroll"
+      onEvent={fn().mockName('onEvent')}
+    />
+    <PrintChecksFailure.Footer onEvent={fn().mockName('onEvent')} />
+  </>
+)

src/components/Payroll/PrintChecks/PrintChecksFailure/PrintChecksFailure.test.tsx

@@ -0,0 +1,40 @@
+import { describe, expect, it, vi } from 'vitest'
+import { screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { PrintChecksFailure } from './PrintChecksFailure'
+import { renderWithProviders } from '@/test-utils/renderWithProviders'
+import { printChecksEvents } from '@/shared/constants'
+
+describe('PrintChecksFailure', () => {
+  const user = userEvent.setup()
+
+  it('renders the error message', async () => {
+    renderWithProviders(
+      <PrintChecksFailure
+        errorMessage="Cannot generate checks on an unprocessed payroll"
+        onEvent={vi.fn()}
+      />,
+    )
+
+    expect(await screen.findByText("We couldn't generate your checks")).toBeInTheDocument()
+    expect(screen.getByText('Cannot generate checks on an unprocessed payroll')).toBeInTheDocument()
+  })
+
+  it('fires PRINT_CHECKS_RETRY when the retry button is clicked', async () => {
+    const onEvent = vi.fn()
+    renderWithProviders(<PrintChecksFailure onEvent={onEvent} />)
+
+    await user.click(await screen.findByRole('button', { name: 'Try again' }))
+
+    expect(onEvent).toHaveBeenCalledWith(printChecksEvents.PRINT_CHECKS_RETRY)
+  })
+
+  it('fires PRINT_CHECKS_CLOSE when the Footer close button is clicked', async () => {
+    const onEvent = vi.fn()
+    renderWithProviders(<PrintChecksFailure.Footer onEvent={onEvent} />)
+
+    await user.click(await screen.findByRole('button', { name: 'Close' }))
+
+    expect(onEvent).toHaveBeenCalledWith(printChecksEvents.PRINT_CHECKS_CLOSE)
+  })
+})