feat(SDK-1161): add PrintChecksBanner

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

@@ -5003,6 +5003,8 @@ export interface Resources {
     // (undocumented)
     'Payroll.PayrollReceipts': Translations.PayrollPayrollReceipts
     // (undocumented)
+    'Payroll.PrintChecksBanner': Translations.PayrollPrintChecksBanner
+    // (undocumented)
     'Payroll.PrintChecksFailure': Translations.PayrollPrintChecksFailure
     // (undocumented)
     'Payroll.PrintChecksSummary': Translations.PayrollPrintChecksSummary

docs/reference/Translations/index.md

@@ -5238,6 +5238,23 @@ 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
@@ -5643,6 +5660,7 @@ 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) |

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/i18n/en/Payroll.PrintChecksBanner.json

@@ -0,0 +1,6 @@
+{
+  "title_one": "You noted {{count}} employee that should be paid by check.",
+  "title_other": "You noted {{count}} employees that should be paid by check.",
+  "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.",
+  "cta": "View and print checks"
+}

src/i18n/types.d.ts

@@ -127,6 +127,7 @@ export interface Resources {
   'Payroll.PayrollList': Translations.PayrollPayrollList
   'Payroll.PayrollOverview': Translations.PayrollPayrollOverview
   'Payroll.PayrollReceipts': Translations.PayrollPayrollReceipts
+  'Payroll.PrintChecksBanner': Translations.PayrollPrintChecksBanner
   'Payroll.PrintChecksFailure': Translations.PayrollPrintChecksFailure
   'Payroll.PrintChecksSummary': Translations.PayrollPrintChecksSummary
   'Payroll.RecoveryCasesList': Translations.PayrollRecoveryCasesList
@@ -7675,6 +7676,17 @@ export namespace Translations {
       totalEmployees_other: string
     }
   }
+  /** Translation keys for the `Payroll.PrintChecksBanner` i18n namespace. */
+  export interface PayrollPrintChecksBanner {
+    /** @defaultValue `"You noted {{count}} employee that should be paid by check."` */
+    title_one: string
+    /** @defaultValue `"You noted {{count}} employees that should be paid by check."` */
+    title_other: string
+    /** @defaultValue `"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."` */
+    description: string
+    /** @defaultValue `"View and print checks"` */
+    cta: string
+  }
   /** Translation keys for the `Payroll.PrintChecksFailure` i18n namespace. */
   export interface PayrollPrintChecksFailure {
     /** @defaultValue `"We couldn't generate your checks"` */