@gusto/embedded-react-sdk 0.55.6 → 0.55.7

package/dist/src/components/Payroll/PayrollConfiguration/__fixtures__/payrollConfigurationMocks.d.ts

@@ -0,0 +1,276 @@
+import { HttpHandler } from 'msw';
+/**
+ * Shared, parameterizable mock data + MSW handlers for the PayrollConfiguration
+ * container tests and the usePayrollConfiguration / usePayrollGrossUp hook tests.
+ *
+ * All shapes are the snake_case JSON the API returns (the SDK client normalizes
+ * to camelCase), so these plug directly into MSW resolvers.
+ */
+interface EmployeeFixtureOptions {
+    rate?: string;
+    paymentMethod?: string;
+}
+export declare const createEmployee: (uuid: string, firstName: string, lastName: string, { rate, paymentMethod }?: EmployeeFixtureOptions) => {
+    uuid: string;
+    first_name: string;
+    last_name: string;
+    payment_method: string;
+    jobs: {
+        uuid: string;
+        title: string;
+        primary: boolean;
+        compensations: {
+            uuid: string;
+            rate: string;
+            payment_unit: string;
+            flsa_status: string;
+        }[];
+    }[];
+};
+interface CompensationFixtureOptions {
+    grossPay?: number;
+    excluded?: boolean;
+    paymentMethod?: string;
+    fixedCompensations?: Array<Record<string, unknown>>;
+}
+export declare const createCompensation: (employeeUuid: string, { grossPay, excluded, paymentMethod, fixedCompensations, }?: CompensationFixtureOptions) => {
+    excluded: boolean;
+    payment_method: string;
+    memo: null;
+    fixed_compensations: Record<string, unknown>[];
+    hourly_compensations: {
+        flsa_status: string;
+        name: string;
+        job_uuid: string;
+        amount: string;
+        compensation_multiplier: number;
+        hours: string;
+    }[];
+    employee_uuid: string;
+    version: string;
+    paid_time_off: never[];
+    gross_pay: string;
+    net_pay: string;
+    check_amount: string;
+};
+export declare const page1Employees: {
+    uuid: string;
+    first_name: string;
+    last_name: string;
+    payment_method: string;
+    jobs: {
+        uuid: string;
+        title: string;
+        primary: boolean;
+        compensations: {
+            uuid: string;
+            rate: string;
+            payment_unit: string;
+            flsa_status: string;
+        }[];
+    }[];
+}[];
+export declare const page2Employees: {
+    uuid: string;
+    first_name: string;
+    last_name: string;
+    payment_method: string;
+    jobs: {
+        uuid: string;
+        title: string;
+        primary: boolean;
+        compensations: {
+            uuid: string;
+            rate: string;
+            payment_unit: string;
+            flsa_status: string;
+        }[];
+    }[];
+}[];
+export declare const allEmployees: {
+    uuid: string;
+    first_name: string;
+    last_name: string;
+    payment_method: string;
+    jobs: {
+        uuid: string;
+        title: string;
+        primary: boolean;
+        compensations: {
+            uuid: string;
+            rate: string;
+            payment_unit: string;
+            flsa_status: string;
+        }[];
+    }[];
+}[];
+export declare const allCompensations: {
+    excluded: boolean;
+    payment_method: string;
+    memo: null;
+    fixed_compensations: Record<string, unknown>[];
+    hourly_compensations: {
+        flsa_status: string;
+        name: string;
+        job_uuid: string;
+        amount: string;
+        compensation_multiplier: number;
+        hours: string;
+    }[];
+    employee_uuid: string;
+    version: string;
+    paid_time_off: never[];
+    gross_pay: string;
+    net_pay: string;
+    check_amount: string;
+}[];
+export declare const mockPaySchedule: {
+    uuid: string;
+    frequency: string;
+    anchor_pay_date: string;
+    anchor_end_of_pay_period: string;
+    custom_name: string;
+    active: boolean;
+    version: string;
+};
+interface PayrollStatusMetaFixture {
+    cancellable?: boolean;
+    payroll_late?: boolean;
+    initial_check_date?: string;
+    expected_check_date?: string;
+    expected_debit_time?: string;
+    initial_debit_cutoff_time?: string;
+}
+export interface BuildPayrollOptions {
+    processed?: boolean;
+    checkDate?: string | null;
+    payrollDeadline?: string | null;
+    calculatedAt?: string | null;
+    processingRequest?: {
+        status: string;
+        errors: unknown[];
+    } | null;
+    employeeCompensations?: Array<Record<string, unknown>>;
+    payrollStatusMeta?: PayrollStatusMetaFixture;
+    offCycle?: boolean;
+    offCycleReason?: string | null;
+    external?: boolean;
+}
+/**
+ * Builds a payroll `GET`/`prepare` response body. Every field has a sensible
+ * default; pass overrides for the dimension a test cares about (calculation
+ * status, processed, off-cycle category, late-payroll meta, etc.).
+ */
+export declare const buildPayrollData: ({ processed, checkDate, payrollDeadline, calculatedAt, processingRequest, employeeCompensations, payrollStatusMeta, offCycle, offCycleReason, external, }?: BuildPayrollOptions) => {
+    uuid: string;
+    payroll_uuid: string;
+    company_uuid: string;
+    off_cycle: boolean;
+    off_cycle_reason: string | null;
+    external: boolean;
+    processed: boolean;
+    check_date: string | null;
+    payroll_deadline: string | null;
+    calculated_at: string | null;
+    pay_period: {
+        start_date: string;
+        end_date: string;
+        pay_schedule_uuid: string;
+    };
+    employee_compensations: Record<string, unknown>[];
+    totals: {
+        gross_pay: string;
+        net_pay: string;
+        company_debit: string;
+        net_pay_debit: string;
+        tax_debit: string;
+        reimbursement_debit: string;
+        child_support_debit: string;
+        reimbursements: string;
+        employee_bonuses: string;
+        employee_commissions: string;
+        employee_cash_tips: string;
+        employee_paycheck_tips: string;
+        additional_earnings: string;
+        owners_draw: string;
+        check_amount: string;
+        employer_taxes: string;
+        employee_taxes: string;
+        benefits: string;
+        employee_benefits_deductions: string;
+        deferred_payroll_taxes: string;
+        other_deductions: string;
+    };
+    payroll_status_meta: PayrollStatusMetaFixture;
+    processing_request: {
+        status: string;
+        errors: unknown[];
+    } | null;
+};
+/**
+ * Default payroll fixture: a regular, unprocessed, already-calculated payroll.
+ */
+export declare const mockPayrollData: {
+    uuid: string;
+    payroll_uuid: string;
+    company_uuid: string;
+    off_cycle: boolean;
+    off_cycle_reason: string | null;
+    external: boolean;
+    processed: boolean;
+    check_date: string | null;
+    payroll_deadline: string | null;
+    calculated_at: string | null;
+    pay_period: {
+        start_date: string;
+        end_date: string;
+        pay_schedule_uuid: string;
+    };
+    employee_compensations: Record<string, unknown>[];
+    totals: {
+        gross_pay: string;
+        net_pay: string;
+        company_debit: string;
+        net_pay_debit: string;
+        tax_debit: string;
+        reimbursement_debit: string;
+        child_support_debit: string;
+        reimbursements: string;
+        employee_bonuses: string;
+        employee_commissions: string;
+        employee_cash_tips: string;
+        employee_paycheck_tips: string;
+        additional_earnings: string;
+        owners_draw: string;
+        check_amount: string;
+        employer_taxes: string;
+        employee_taxes: string;
+        benefits: string;
+        employee_benefits_deductions: string;
+        deferred_payroll_taxes: string;
+        other_deductions: string;
+    };
+    payroll_status_meta: PayrollStatusMetaFixture;
+    processing_request: {
+        status: string;
+        errors: unknown[];
+    } | null;
+};
+interface PayrollHandlersOptions {
+    /** Read the current payroll body on each request so tests can mutate it mid-flow. */
+    getPayrollData: () => ReturnType<typeof buildPayrollData>;
+    /** Employees returned by the paginated list endpoint. Defaults to all 27. */
+    employees?: Array<ReturnType<typeof createEmployee>>;
+    /** Pay schedule returned by the pay-schedule endpoint. */
+    paySchedule?: typeof mockPaySchedule;
+    /** Blockers returned by the blockers endpoint. Defaults to none. */
+    blockers?: unknown[];
+}
+/**
+ * The standard set of MSW handlers a PayrollConfiguration render needs: blockers,
+ * paginated employees list, payroll `GET`, `prepare` (filtered by requested UUIDs),
+ * and pay schedule. Tests spread these into `server.use(...)` and add/override
+ * endpoint handlers (e.g. `calculate`) as needed.
+ */
+export declare const buildPayrollConfigurationHandlers: ({ getPayrollData, employees, paySchedule, blockers, }: PayrollHandlersOptions) => HttpHandler[];
+export {};

package/dist/{components → src/components}/Payroll/PayrollEditEmployee/shared/usePayrollEditEmployeeForm/fields.d.ts

@@ -2,21 +2,32 @@ import { ComponentType } from 'react';
 import { PayrollEmployeeCompensationsType } from '@gusto/embedded-api/models/components/payrollemployeecompensationstype';
 import { PayrollUpdatePaymentMethod } from '@gusto/embedded-api/models/components/payrollupdate';
 import { NormalizedWorkweek } from './payrollEditEmployeeHelpers';
+import { PayrollEditEmployeeErrorCode } from './payrollEditEmployeeSchema';
 import { RadioGroupHookFieldProps } from '../../../../../partner-hook-utils/form/fields/RadioGroupHookField';
 import { HookFieldProps } from '../../../../../partner-hook-utils/types';
 import { TextInputProps } from '../../../../Common/UI/TextInput/TextInputTypes';
 import { PayrollCategory } from '../../../payrollTypes';
+/**
+ * Display copy for each validation error code a bound field can surface, so the
+ * consumer supplies error text once (keyed by code) rather than reconstructing
+ * form paths or hardcoding which rule each field can fail. Partial: a missing
+ * code falls back to the raw error code.
+ *
+ * @public
+ */
+export type PayrollEditEmployeeErrorMessages = Partial<Record<PayrollEditEmployeeErrorCode, string>>;
 /**
  * Presentation props accepted by a bound numeric field in the payroll editor.
  *
  * @remarks
- * The hook binds the react-hook-form `name` and forces `type="number"`
- * internally; the UI supplies copy and layout props (label, adornments,
- * `shouldVisuallyHideLabel`, required state).
+ * The hook binds the react-hook-form `name`, forces `type="number"`, and
+ * resolves the field's own validation message internally; the UI supplies copy
+ * and layout props (label, adornments, `shouldVisuallyHideLabel`, required
+ * state, `description`).
  *
  * @public
  */
-export type PayrollEditEmployeeFieldProps = Omit<TextInputProps, 'name' | 'value' | 'onChange' | 'isInvalid' | 'type' | 'min'>;
+export type PayrollEditEmployeeFieldProps = Omit<TextInputProps, 'name' | 'value' | 'onChange' | 'isInvalid' | 'type' | 'min' | 'errorMessage'>;
 /**
  * A numeric field component pre-bound by the hook to a specific form path.
  *
@@ -91,6 +102,13 @@ export interface TimeOffEntry {
     name: string;
     /** Field component pre-bound to this entry's form path. */
     Field: PayrollEditEmployeeFieldComponent;
+    /**
+     * The policy's remaining balance after the entered hours are subtracted,
+     * recomputed live as the user edits. `null` when the policy has no tracked
+     * accrual balance (e.g. final-payout rows). Feed it into the field's own
+     * `description` to render it as the input's help text.
+     */
+    remaining: number | null;
 }
 /**
  * One entry in the flat `other` section.
@@ -111,16 +129,17 @@ export interface OtherEntry {
     Field: PayrollEditEmployeeFieldComponent;
 }
 /**
- * Per-job hours and additional-earnings sections.
+ * A single job's hours section.
  *
  * @remarks
- * An employee can hold multiple jobs, each with its own hourly and additional
- * earnings lines. Each section is either a flat `Entry[]` (single-workweek, or an
- * overtime-ineligible employee) OR a `Record<workweekStart, Entry[]>`
- * (multi-workweek and overtime-eligible). The value type is the signal — array is
- * flat, object is split by workweek; use {@link isSplitByWorkweek} to
- * discriminate. `title` is the job's display title (entity data, not copy) for
- * rendering a per-job heading.
+ * An employee can hold multiple jobs, each with its own hourly lines. `hours` is
+ * either a flat `Entry[]` (single-workweek, or an overtime-ineligible employee)
+ * OR a `Record<workweekStart, Entry[]>` (multi-workweek and overtime-eligible).
+ * The value type is the signal — array is flat, object is split by workweek; use
+ * {@link isSplitByWorkweek} to discriminate. `title` is the job's display title
+ * (entity data, not copy) for rendering a per-job heading. Earnings are not
+ * job-scoped: they live in the employee-level `additionalEarnings` and
+ * `otherEarnings` sections on {@link PayrollEditEmployeeFields}.
  *
  * @public
  */
@@ -129,10 +148,11 @@ export interface JobFields {
     jobUuid: string;
     /** The job's display title, when available, for a per-job heading. */
     title?: string;
-    /** Hours inputs for this job. */
+    /**
+     * Hours inputs for this job. Excludes Overtime/Double-overtime rows while
+     * `data.withOvertime` is `false`.
+     */
     hours: HourEntry[] | Record<string, HourEntry[]>;
-    /** Overtime-affecting earnings for this job. */
-    additionalEarnings: EarningEntry[] | Record<string, EarningEntry[]>;
 }
 /**
  * Presentation props accepted by a bound reimbursement description (text) field.
@@ -195,18 +215,25 @@ export interface ReimbursementRow {
  * The render-ready field collections exposed on `form.Fields`.
  *
  * @remarks
- * Job-scoped inputs (hours, additional earnings) are grouped under `jobs`, one
- * entry per job, so multi-job employees render correctly. Employee-scoped
- * sections (other earnings, time off, final payout, payment method,
- * reimbursements) stay top-level.
+ * Hours are grouped under `jobs`, one entry per job, so multi-job employees
+ * render correctly. All earnings and the remaining sections are employee-scoped
+ * and stay top-level: `additionalEarnings` (overtime-affecting) and
+ * `otherEarnings` (non-overtime) each render as a single section spanning every
+ * job, alongside time off, final payout, payment method, and reimbursements.
  *
  * @public
  */
 export interface PayrollEditEmployeeFields {
-    /** Per-job hours and additional-earnings sections; one entry per job. */
+    /** Per-job hours sections; one entry per job. */
     jobs: JobFields[];
+    /**
+     * Overtime-affecting earnings across all jobs, as a single employee-level
+     * section. Flat `Entry[]` when unsplit, or `Record<workweekStart, Entry[]>`
+     * when split by workweek; use {@link isSplitByWorkweek} to discriminate.
+     */
+    additionalEarnings: EarningEntry[] | Record<string, EarningEntry[]>;
     /** Non-overtime earnings (e.g. tips), always flat; opaque render entries. */
-    other: OtherEntry[];
+    otherEarnings: OtherEntry[];
     /** Time-off inputs (never workweek-breakdown). */
     timeOff: TimeOffEntry[];
     /** Final-payout inputs, present only for dismissal payrolls. */
@@ -235,10 +262,11 @@ export declare function isSplitByWorkweek<TEntry>(section: TEntry[] | Record<str
  * Builds the draft "add reimbursement" field group, binding its Description and
  * Amount fields to the `reimbursementDraft` form path.
  *
+ * @param errorMessages - Copy for each validation error code, baked into the amount field so it self-resolves.
  * @returns The pre-bound draft field group for `form.Fields.reimbursementDraft`.
  * @internal
  */
-export declare function createReimbursementDraftFields(): ReimbursementDraftFields;
+export declare function createReimbursementDraftFields(errorMessages?: PayrollEditEmployeeErrorMessages): ReimbursementDraftFields;
 /** @internal */
 export interface CreatePayrollEditEmployeeFieldsOptions {
     employeeCompensation: PayrollEmployeeCompensationsType | undefined;
@@ -254,9 +282,31 @@ export interface CreatePayrollEditEmployeeFieldsOptions {
     overtimeEarningNames: Set<string>;
     /** Whether the employee is overtime-eligible (nonexempt family). Gates per-workweek splitting. */
     isOvertimeEligible: boolean;
+    /**
+     * Gates per-workweek splitting
+     * alongside `isOvertimeEligible`, and whether Overtime/Double-overtime rows
+     * are included in `hours`.
+     */
+    withOvertime: boolean;
     /** Job title lookup by job UUID, for per-job section headings. */
     jobTitlesByUuid: Map<string, string>;
+    /** Accrual balance by time-off policy name, for the remaining-balance display. */
+    timeOffAccrualByName: Map<string, string>;
+    /** Copy for each validation error code, baked into every bound field so it self-resolves. */
+    errorMessages?: PayrollEditEmployeeErrorMessages;
 }
+/**
+ * A time-off policy's remaining balance: its accrual balance minus the entered
+ * hours. `null` when the policy has no tracked accrual balance (final-payout
+ * rows). Shared by the field builder (seeding the initial value) and the hook
+ * (recomputing it live as the user edits).
+ *
+ * @param accrualBalance - The policy's accrual balance, or `undefined` when untracked.
+ * @param enteredHours - The currently entered hours for the policy.
+ * @returns The remaining balance, or `null` when untracked.
+ * @internal
+ */
+export declare function computeTimeOffRemaining(accrualBalance: string | undefined, enteredHours: string | null | undefined): number | null;
 /**
  * Builds the render-ready {@link PayrollEditEmployeeFields} from the prepared
  * compensation.
@@ -271,8 +321,8 @@ export interface CreatePayrollEditEmployeeFieldsOptions {
  * final payout is added only for dismissal payrolls, and the payment-method
  * selector appears only when direct deposit is set up.
  *
- * @param options - The prepared compensation, normalized workweeks, payroll category, direct-deposit flag, overtime earning names, eligibility, and job titles.
+ * @param options - The prepared compensation, normalized workweeks, payroll category, direct-deposit flag, overtime earning names, eligibility, the `withOvertime` flag, job titles, time-off accrual balances and entered values, and error copy.
  * @returns The populated field collections.
  * @internal
  */
-export declare function createPayrollEditEmployeeFields({ employeeCompensation, fixedCompensations, workweeks, payrollCategory, hasDirectDepositSetup, overtimeEarningNames, isOvertimeEligible, jobTitlesByUuid, }: CreatePayrollEditEmployeeFieldsOptions): PayrollEditEmployeeFields;
+export declare function createPayrollEditEmployeeFields({ employeeCompensation, fixedCompensations, workweeks, payrollCategory, hasDirectDepositSetup, overtimeEarningNames, isOvertimeEligible, withOvertime, jobTitlesByUuid, timeOffAccrualByName, errorMessages, }: CreatePayrollEditEmployeeFieldsOptions): PayrollEditEmployeeFields;

package/dist/{components → src/components}/Payroll/PayrollEditEmployee/shared/usePayrollEditEmployeeForm/payrollEditEmployeeHelpers.d.ts

@@ -7,11 +7,11 @@ import { PayrollCategory } from '../../../payrollTypes';
 /** One fixed-compensation line off the prepared compensation. */
 type FixedCompensationEntry = NonNullable<PayrollEmployeeCompensationsType['fixedCompensations']>[number];
 /**
- * Internal normalized form of a workweek: the API exposes
+ * Normalized form of a workweek: the API exposes
  * `{ startDate?: RFCDate; endDate?: RFCDate }`, but the hook keys week-maps by
  * `YYYY-MM-DD` strings and builds breakdowns from them, so both boundaries are
- * required strings here. Not part of the public surface — partners read the raw
- * workweeks off `data.preparedPayroll.workweeks` (the API type).
+ * required strings here. Surfaced on the hook's `data.workweeks` so the UI can
+ * label each per-workweek column without re-parsing the raw API workweeks.
  *
  * @internal
  */
@@ -73,36 +73,83 @@ export declare function collectOvertimeEarningNames(earningTypeList: EarningType
 export declare function resolveEditableFixedCompensations(existingFixedCompensations: FixedCompensationEntry[] | undefined, fixedCompensationTypes: Array<{
     name?: string | null;
 }> | undefined, primaryJobUuid: string | undefined, flsaStatus: string | undefined): FixedCompensationEntry[];
+/**
+ * Whether the employee's prepared compensation already carries non-zero
+ * Overtime or Double-overtime hours.
+ *
+ * @remarks
+ * Used to default the single `withOvertime` flag: an employee who already
+ * has real overtime hours starts with the workweek split shown rather than
+ * requiring an extra click to see data that's already there.
+ *
+ * @param hourlyCompensations - The prepared compensation's hourly lines.
+ * @returns `true` when any Overtime or Double-overtime line has hours greater than zero.
+ * @internal
+ */
+export declare function hasExistingOvertimeHours(hourlyCompensations: PayrollEmployeeCompensationsType['hourlyCompensations'] | undefined): boolean;
+/**
+ * Whether any of the employee's hourly-compensation lines already carries a
+ * real, per-workweek `breakdowns` array that exactly tiles the current pay
+ * period's workweeks.
+ *
+ * @remarks
+ * Used alongside {@link hasExistingOvertimeHours} to default the single
+ * `withOvertime` flag: an employee whose hours are already broken down by
+ * workweek (e.g. a previous edit entered real per-week values) starts with the
+ * workweek split shown, seeded from those breakdowns rather than from a blank
+ * or first-cell-only guess. See {@link buildWeekMap}, which applies the same
+ * per-line check to decide each line's population mode.
+ *
+ * @param hourlyCompensations - The prepared compensation's hourly lines.
+ * @param workweeks - Normalized workweeks for the pay period.
+ * @returns `true` when at least one hourly line's breakdowns cover every workweek.
+ * @internal
+ */
+export declare function hasBreakdownsMatchingWorkweeks(hourlyCompensations: PayrollEmployeeCompensationsType['hourlyCompensations'] | undefined, workweeks: NormalizedWorkweek[]): boolean;
 /**
  * Derives the form's default values from the employee's prepared compensation.
  *
  * @remarks
- * Hourly and additional earnings are expanded into per-workweek maps from each
- * compensation's `breakdowns` (or its total for the single-workweek case). Time
- * off, final payout, reimbursements, and payment method are read straight off
- * the compensation.
+ * Hourly and additional earnings are expanded into per-workweek maps via
+ * {@link buildWeekMap}: collapsed to the total when not split, seeded from real
+ * breakdowns or first-cell-only otherwise. Time off, final payout,
+ * reimbursements, and payment method are read straight off the compensation.
  *
  * @param employeeCompensation - The employee's prepared compensation, if loaded.
  * @param workweeks - Normalized workweeks for the pay period.
+ * @param withOvertime - The single, form-wide overtime-mode flag (see {@link hasExistingOvertimeHours}, {@link hasBreakdownsMatchingWorkweeks}, `actions.addOvertime`). Gates splitting alongside `isOvertimeEligible`.
  * @returns Default {@link PayrollEditEmployeeFormData} for `useForm`.
  * @internal
  */
-export declare function derivePayrollEditEmployeeDefaults(employeeCompensation: PayrollEmployeeCompensationsType | undefined, workweeks: NormalizedWorkweek[], hasDirectDepositSetup: boolean, overtimeEarningNames: Set<string>, isOvertimeEligible: boolean, fixedCompensations?: FixedCompensationEntry[]): PayrollEditEmployeeFormData;
+export declare function derivePayrollEditEmployeeDefaults(employeeCompensation: PayrollEmployeeCompensationsType | undefined, workweeks: NormalizedWorkweek[], hasDirectDepositSetup: boolean, overtimeEarningNames: Set<string>, isOvertimeEligible: boolean, withOvertime: boolean, fixedCompensations?: FixedCompensationEntry[]): PayrollEditEmployeeFormData;
 /**
  * Builds the `PayrollUpdate` employee-compensation payload from form values.
  *
  * @remarks
- * When the pay period spans a single workweek, totals are sent without
- * `breakdowns`. When it spans multiple workweeks, each hourly and additional
- * earning carries `breakdowns` tiling every workweek exactly (no gaps or
- * overlaps), with the total equal to the sum of the per-workweek values.
+ * When the pay period spans a single workweek (or the employee isn't split by
+ * workweek), totals are sent without `breakdowns`. When split, each hourly and
+ * additional-earning line is decided independently — per line, not per job
+ * (the API models breakdowns on each compensation line, not as a per-job
+ * all-or-nothing unit):
+ *
+ * - A fully-filled line (every workweek cell has a value) sends `breakdowns`
+ *   tiling every workweek exactly, with the total equal to the sum of the
+ *   per-week values.
+ * - An entirely blank line sends nothing for it — no `breakdowns`, no
+ *   fabricated `0`, no fabricated total — leaving it as the flat, untouched
+ *   value it already was.
+ * - A partial line (some but not all cells filled) can never reach this
+ *   function: {@link createPayrollEditEmployeeSchema}'s per-row check blocks
+ *   submit until every cell in a touched row is filled.
  *
  * @param formData - Current parsed form values.
  * @param employeeCompensation - The prepared compensation, for identifying metadata (`version`, `employeeUuid`).
  * @param workweeks - Normalized workweeks for the pay period.
  * @param payrollCategory - The payroll category, gating itemized vs. off-cycle reimbursements.
+ * @param isOvertimeEligible - Whether the employee is overtime-eligible (nonexempt family).
+ * @param withOvertime - The single, form-wide overtime-mode flag. Gates splitting alongside `isOvertimeEligible` and `workweeks.length > 1`; when `false`, every line submits its flat (collapsed) value regardless of eligibility.
  * @returns The employee-compensation entry for the `PayrollUpdate` request body.
  * @internal
  */
-export declare function buildPayrollUpdateEmployeeCompensation(formData: PayrollEditEmployeeFormOutputs, employeeCompensation: PayrollEmployeeCompensationsType | undefined, workweeks: NormalizedWorkweek[], payrollCategory: PayrollCategory, isOvertimeEligible: boolean): PayrollUpdateEmployeeCompensations;
+export declare function buildPayrollUpdateEmployeeCompensation(formData: PayrollEditEmployeeFormOutputs, employeeCompensation: PayrollEmployeeCompensationsType | undefined, workweeks: NormalizedWorkweek[], payrollCategory: PayrollCategory, isOvertimeEligible: boolean, withOvertime: boolean): PayrollUpdateEmployeeCompensations;
 export {};

package/dist/{components → src/components}/Payroll/PayrollEditEmployee/shared/usePayrollEditEmployeeForm/payrollEditEmployeeSchema.d.ts

@@ -20,6 +20,7 @@ export declare const PAYMENT_METHOD_OPTIONS: {
 export declare const PayrollEditEmployeeErrorCodes: {
     readonly NEGATIVE_AMOUNT: "NEGATIVE_AMOUNT";
     readonly REIMBURSEMENT_AMOUNT: "REIMBURSEMENT_AMOUNT";
+    readonly REQUIRED_WORKWEEK: "REQUIRED_WORKWEEK";
 };
 /**
  * Union of validation error codes emitted by the payroll edit-employee schema.
@@ -45,11 +46,20 @@ export declare const reimbursementDraftSchema: z.ZodObject<{
  * @remarks
  * Overtime-affecting values are keyed by workweek internally: hours and
  * additional earnings are job-then-name-then-workweekStart records, so the
- * single-workweek case is just the degenerate one-key form of the multi-workweek
- * shape. Non-overtime earnings (other) are flat job-then-name-to-amount records
- * with no per-workweek breakdown, since they do not feed the blended rate. Time
- * off and final payout are keyed by compensation name. This keeps one schema and
- * one submit path.
+ * single-workweek (or not-yet-split) case is just the degenerate one-key form
+ * of the multi-workweek shape. Non-overtime earnings (other) are flat
+ * job-then-name-to-amount records with no per-workweek breakdown, since they do
+ * not feed the blended rate. Time off and final payout are keyed by
+ * compensation name. This keeps one schema and one submit path.
+ *
+ * A `superRefine` enforces per-row completeness on `hours` and
+ * `additionalEarnings`: once any workweek cell in a job+name row is filled, every
+ * other cell in that row must be filled too, surfaced per empty cell as
+ * {@link PayrollEditEmployeeErrorCodes.REQUIRED_WORKWEEK}. A row with nothing
+ * filled is left alone (still submittable as untouched). This needs no
+ * workweek/split context passed in — it's purely structural on whatever keys a
+ * row happens to have, which is why a collapsed row (always exactly one key)
+ * can never trigger it.
  *
  * @returns The Zod schema validating {@link PayrollEditEmployeeFormData}.
  * @internal