feat(SDK-1161): add PrintChecksForm

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

@@ -129,6 +129,7 @@ import { FunctionComponent } from 'react';
 import { Garnishment } from '@gusto/embedded-api/models/components/garnishment';
 import { GarnishmentChildSupport } from '@gusto/embedded-api/models/components/garnishmentchildsupport';
 import { GarnishmentType } from '@gusto/embedded-api/models/components/garnishment';
+import { GeneratedDocumentStatus } from '@gusto/embedded-api/models/components/generateddocument';
 import { HolidayPayPolicy } from '@gusto/embedded-api/models/components/holidaypaypolicy';
 import { HolidayPayPolicyEmployees } from '@gusto/embedded-api/models/components/holidaypaypolicy';
 import { HourlyCompensations } from '@gusto/embedded-api/models/components/payrollemployeecompensationstype';
@@ -247,6 +248,8 @@ import { PayScheduleShow } from '@gusto/embedded-api/models/components/payschedu
 import { PlaidStatus } from '@gusto/embedded-api/models/components/companybankaccount';
 import { PolicyType } from '@gusto/embedded-api/models/components/timeoffpolicy';
 import { PresidentsDay } from '@gusto/embedded-api/models/components/holidaypaypolicy';
+import { PrintablePayrollChecksBody } from '@gusto/embedded-api/models/components/printablepayrollchecksbody';
+import { PrintingFormat } from '@gusto/embedded-api/models/components/printablepayrollchecksbody';
 import { QueryClient } from '@tanstack/react-query';
 import { Questions } from '@gusto/embedded-api/models/components/employeestatetaxesrequest';
 import { RateType } from '@gusto/embedded-api/models/components/taxrequirementmetadata';
@@ -537,6 +540,7 @@ declare namespace APIModels {
         Garnishment,
         GarnishmentChildSupport,
         PaymentPeriod,
+        GeneratedDocumentStatus,
         ChristmasDay,
         ColumbusDay,
         HolidayPayPolicyEmployees,
@@ -656,6 +660,8 @@ declare namespace APIModels {
         PayScheduleFrequency_2 as PayScheduleFrequency,
         PaySchedulePreviewPayPeriod,
         PayScheduleShow,
+        PrintablePayrollChecksBody,
+        PrintingFormat,
         RecoveryCase,
         RecoveryCaseStatus,
         IdentityVerificationStatus,
@@ -1293,6 +1299,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 +5006,14 @@ export interface Resources {
     // (undocumented)
     'Payroll.PayrollReceipts': Translations.PayrollPayrollReceipts
     // (undocumented)
+    'Payroll.PrintChecksBanner': Translations.PayrollPrintChecksBanner
+    // (undocumented)
+    'Payroll.PrintChecksFailure': Translations.PayrollPrintChecksFailure
+    // (undocumented)
+    'Payroll.PrintChecksForm': Translations.PayrollPrintChecksForm
+    // (undocumented)
+    'Payroll.PrintChecksSummary': Translations.PayrollPrintChecksSummary
+    // (undocumented)
     'Payroll.RecoveryCasesList': Translations.PayrollRecoveryCasesList
     // (undocumented)
     'Payroll.RecoveryCasesResubmit': Translations.PayrollRecoveryCasesResubmit

docs/reference/APIModels/index.md

@@ -3036,6 +3036,39 @@ Defined in: [gusto\_embedded\_v\_2026\_06\_15/src/models/components/garnishment.
 
 ***
 
+<a id="generateddocumentstatus"></a>
+
+## GeneratedDocumentStatus
+
+> `const` **GeneratedDocumentStatus**: `object`
+
+Defined in: [gusto\_embedded\_v\_2026\_06\_15/src/models/components/generateddocument.ts:15](https://github.com/Gusto/gusto-typescript-client/blob/gusto_embedded_v_2026_06_15/v0.1.0/gusto_embedded_v_2026_06_15/src/models/components/generateddocument.ts#L15)
+
+Current status of the Generated Document
+
+### Type Declaration
+
+| Name | Type |
+| ------ | ------ |
+| <a id="property-generateddocumentstatusfailed"></a> `Failed` | `"failed"` |
+| <a id="property-generateddocumentstatuspending"></a> `Pending` | `"pending"` |
+| <a id="property-generateddocumentstatusstarted"></a> `Started` | `"started"` |
+| <a id="property-generateddocumentstatussucceeded"></a> `Succeeded` | `"succeeded"` |
+
+***
+
+<a id="generateddocumentstatus-1"></a>
+
+## GeneratedDocumentStatus
+
+> **GeneratedDocumentStatus** = `ClosedEnum`\<*typeof* [`GeneratedDocumentStatus`](#generateddocumentstatus)\>
+
+Defined in: [gusto\_embedded\_v\_2026\_06\_15/src/models/components/generateddocument.ts:15](https://github.com/Gusto/gusto-typescript-client/blob/gusto_embedded_v_2026_06_15/v0.1.0/gusto_embedded_v_2026_06_15/src/models/components/generateddocument.ts#L15)
+
+Current status of the Generated Document
+
+***
+
 <a id="holidaypaypolicy"></a>
 
 ## HolidayPayPolicy
@@ -6028,6 +6061,56 @@ Defined in: [gusto\_embedded\_v\_2026\_06\_15/src/models/components/holidaypaypo
 
 ***
 
+<a id="printablepayrollchecksbody"></a>
+
+## PrintablePayrollChecksBody
+
+> **PrintablePayrollChecksBody** = `object`
+
+Defined in: [gusto\_embedded\_v\_2026\_06\_15/src/models/components/printablepayrollchecksbody.ts:24](https://github.com/Gusto/gusto-typescript-client/blob/gusto_embedded_v_2026_06_15/v0.1.0/gusto_embedded_v_2026_06_15/src/models/components/printablepayrollchecksbody.ts#L24)
+
+Request body for generating printable payroll checks.
+
+### Properties
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="property-printablepayrollchecksbodyprintingformat"></a> `printingFormat` | [`PrintingFormat`](#printingformat-1) | The type of check stock being printed. Check the "Types of check stock" section in this [link](https://support.gusto.com/article/999877761000000/Pay-your-team-by-check) for more info on check types |
+| <a id="property-printablepayrollchecksbodystartingchecknumber"></a> `startingCheckNumber?` | `number` | The starting check number we will start generating checks from. Use to override the sequence that will be used to generate check numbers. |
+
+***
+
+<a id="printingformat"></a>
+
+## PrintingFormat
+
+> `const` **PrintingFormat**: `object`
+
+Defined in: [gusto\_embedded\_v\_2026\_06\_15/src/models/components/printablepayrollchecksbody.ts:12](https://github.com/Gusto/gusto-typescript-client/blob/gusto_embedded_v_2026_06_15/v0.1.0/gusto_embedded_v_2026_06_15/src/models/components/printablepayrollchecksbody.ts#L12)
+
+The type of check stock being printed. Check the "Types of check stock" section in this [link](https://support.gusto.com/article/999877761000000/Pay-your-team-by-check) for more info on check types
+
+### Type Declaration
+
+| Name | Type |
+| ------ | ------ |
+| <a id="property-printingformatbottom"></a> `Bottom` | `"bottom"` |
+| <a id="property-printingformattop"></a> `Top` | `"top"` |
+
+***
+
+<a id="printingformat-1"></a>
+
+## PrintingFormat
+
+> **PrintingFormat** = `ClosedEnum`\<*typeof* [`PrintingFormat`](#printingformat)\>
+
+Defined in: [gusto\_embedded\_v\_2026\_06\_15/src/models/components/printablepayrollchecksbody.ts:12](https://github.com/Gusto/gusto-typescript-client/blob/gusto_embedded_v_2026_06_15/v0.1.0/gusto_embedded_v_2026_06_15/src/models/components/printablepayrollchecksbody.ts#L12)
+
+The type of check stock being printed. Check the "Types of check stock" section in this [link](https://support.gusto.com/article/999877761000000/Pay-your-team-by-check) for more info on check types
+
+***
+
 <a id="questions"></a>
 
 ## Questions

docs/reference/Translations/index.md

@@ -5234,6 +5234,81 @@ 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="payrollprintchecksform"></a>
+
+### PayrollPrintChecksForm
+
+Translation keys for the `Payroll.PrintChecksForm` i18n namespace.
+
+#### Properties
+
+| Property | Default value |
+| ------ | ------ |
+| <a id="property-payrollprintchecksformblankstockdescription"></a> `blankStockDescription` | `"Use this check stock if you have blank check stock and need us to populate your company and bank information. The physical check will always be on the bottom of the check PDF."` |
+| <a id="property-payrollprintchecksformblankstocklabel"></a> `blankStockLabel` | `"Blank check stock"` |
+| <a id="property-payrollprintchecksformcancelcta"></a> `cancelCta` | `"Cancel"` |
+| <a id="property-payrollprintchecksformcustomstockdescription"></a> `customStockDescription` | `"Use this check stock if you have check stock that is pre-printed with your company and bank information. The physical check will appear on the top of the check PDF. Check numbers should already be pre-printed on the check stock you purchased."` |
+| <a id="property-payrollprintchecksformcustomstocklabel"></a> `customStockLabel` | `"Custom check stock"` |
+| <a id="property-payrollprintchecksformmodaltitle"></a> `modalTitle` | `"Choose check stock"` |
+| <a id="property-payrollprintchecksformstartingchecknumberdescription"></a> `startingCheckNumberDescription` | `"This will be the first check number, all other checks will follow sequentially."` |
+| <a id="property-payrollprintchecksformstartingchecknumberlabel"></a> `startingCheckNumberLabel` | `"Check number starts with"` |
+| <a id="property-payrollprintchecksformsubmitcta"></a> `submitCta` | `"View checks"` |
+| <a id="property-payrollprintchecksformsubmitctaloading"></a> `submitCtaLoading` | `"Generating..."` |
+| <a id="property-payrollprintchecksformvalidations"></a> `validations` | |
+| `validations.startingCheckNumber` | `"Enter a valid check number"` |
+
+***
+
+<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 +5681,10 @@ 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-resourcespayrollprintchecksform"></a> `Payroll.PrintChecksForm` | [`PayrollPrintChecksForm`](#payrollprintchecksform) |
+| <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()
+  })
+})