From ca36102f82e7524c7c097f0fa7d0d57d6cb0cd41 Mon Sep 17 00:00:00 2001
From: Tim Johnson <timjohnson0914@gmail.com>
Date: Fri, 18 Sep 2026 17:18:01 -0400
Subject: [PATCH] MPDX-10004 - Block savings fund transfers that would overdraw
 the account

One-time transfers over the source fund's available balance are now
blocked at the form level ($0 floor, cent-precision comparison,
fail-closed when the fund balance cannot be resolved). Recurring
transfers and edits show a non-blocking overdraft warning instead,
since their payments process in the future against future balances.
The BalanceCard transfer button now gates on the same shared
availableBalance helper instead of the old deficit-limit check.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../BalanceCard/BalanceCard.test.tsx          |   2 +-
 .../BalanceCard/BalanceCard.tsx               |   3 +-
 .../Helper/availableBalance.ts                |  20 ++
 .../TransferModal/TransferModal.test.tsx      | 193 ++++++++++++++++--
 .../TransferModal/TransferModal.tsx           |  69 +++++--
 5 files changed, 256 insertions(+), 31 deletions(-)
 create mode 100644 src/components/HrTools/SavingsFundTransfer/Helper/availableBalance.ts

diff --git a/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.test.tsx b/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.test.tsx
index 36d52d37e..b5bcca49c 100644
--- a/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.test.tsx
+++ b/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.test.tsx
@@ -228,7 +228,7 @@ describe('BalanceCard', () => {
     });
   });
 
-  it('should disable transfer from button when current balance goes beyond deficit limit', async () => {
+  it('should disable transfer from button when the fund has no available balance', async () => {
     const { findByRole } = render(
       <Components
         fund={{
diff --git a/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.tsx b/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.tsx
index 419a7b47d..cf5d6905a 100644
--- a/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.tsx
+++ b/src/components/HrTools/SavingsFundTransfer/BalanceCard/BalanceCard.tsx
@@ -10,6 +10,7 @@ import {
   getIconColorForFundType,
   getIconForFundType,
 } from '../../../Reports/StaffExpenseReport/Helpers/fundTypeHelpers';
+import { availableBalance } from '../Helper/availableBalance';
 import { FundFieldsFragment } from '../ReportsSavingsFund.generated';
 import { TransferModalData } from '../mockData';
 
@@ -123,7 +124,7 @@ export const BalanceCard: React.FC<BalanceCardProps> = ({
       >
         <Button
           onClick={handleTransferFrom}
-          disabled={fund.endBalance <= fund.deficitLimit}
+          disabled={availableBalance(fund) <= 0}
           fullWidth
         >
           <Outbox fontSize="small" sx={{ mr: 0.5 }} />
diff --git a/src/components/HrTools/SavingsFundTransfer/Helper/availableBalance.ts b/src/components/HrTools/SavingsFundTransfer/Helper/availableBalance.ts
new file mode 100644
index 000000000..8555673fe
--- /dev/null
+++ b/src/components/HrTools/SavingsFundTransfer/Helper/availableBalance.ts
@@ -0,0 +1,20 @@
+import { FundFieldsFragment } from '../ReportsSavingsFund.generated';
+
+// The lowest a source account balance may go after a transfer. Per
+// MPDX-10004 a transfer may never take an account below $0 — fund deficit
+// limits apply to salary, not savings fund transfers. If that rule ever
+// loosens to allow a deficit, confirm the sign convention of
+// `deficitLimit` first: BalanceCard formerly treated it as a negative
+// floor (endBalance <= deficitLimit) while TransferModal's old warning
+// treated it as a positive magnitude, and mocks with both conventions
+// exist in the repo.
+export const minimumAllowedBalance = (_fund: FundFieldsFragment): number => 0;
+
+// The most that can be transferred out of a fund right now.
+export const availableBalance = (fund: FundFieldsFragment): number =>
+  fund.endBalance - minimumAllowedBalance(fund);
+
+// Compare money at cent precision: fund balances are floats and can carry
+// sub-cent noise that would otherwise reject the exact amount the UI
+// displays as available.
+export const toCents = (amount: number): number => Math.round(amount * 100);
diff --git a/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.test.tsx b/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.test.tsx
index c508751df..74b5ce0d6 100644
--- a/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.test.tsx
+++ b/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.test.tsx
@@ -2,7 +2,7 @@ import React from 'react';
 import { ThemeProvider } from '@mui/material/styles';
 import { AdapterLuxon } from '@mui/x-date-pickers/AdapterLuxon';
 import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider';
-import { render, waitFor, within } from '@testing-library/react';
+import { RenderResult, render, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { DateTime } from 'luxon';
 import { SnackbarProvider } from 'notistack';
@@ -66,11 +66,13 @@ const transferDefaultData: TransferModalData['transfer'] = {
 interface ComponentsProps {
   transfer?: TransferModalData['transfer'];
   type?: TransferTypeEnum;
+  funds?: typeof fundsMock;
 }
 
 const Components = ({
   transfer = transferDefaultData,
   type,
+  funds = fundsMock,
 }: ComponentsProps) => (
   <SnackbarProvider>
     <ThemeProvider theme={theme}>
@@ -89,7 +91,7 @@ const Components = ({
                   type,
                   transfer,
                 }}
-                funds={fundsMock}
+                funds={funds}
                 lastName={lastName}
                 handleClose={handleClose}
               />
@@ -101,6 +103,21 @@ const Components = ({
   </SnackbarProvider>
 );
 
+const enterTransferDetails = (
+  { getByRole }: RenderResult,
+  amount: string,
+): HTMLElement => {
+  userEvent.click(getByRole('combobox', { name: /to account/i }));
+  userEvent.click(getByRole('option', { name: /staff savings/i }));
+
+  const amountField = getByRole('spinbutton', { name: /amount/i });
+  userEvent.clear(amountField);
+  userEvent.type(amountField, amount);
+  userEvent.tab();
+
+  return amountField;
+};
+
 describe('TransferModal', () => {
   it('should render the modal with correct inputs', () => {
     const { getByRole, getByText } = render(<Components />);
@@ -653,27 +670,169 @@ describe('TransferModal', () => {
       ).toBeInTheDocument();
     });
 
-    it('should show information box when amount exceeds limit', async () => {
-      const { getByRole, findByRole } = render(<Components />);
+    it('should show error and block submission when amount is one cent over the available balance', async () => {
+      const result = render(<Components />);
+      const { getByRole, findByText } = result;
 
-      const toAccount = getByRole('combobox', { name: /to account/i });
+      const amountField = enterTransferDetails(result, '15000.01');
+      expect(amountField).toHaveValue(15000.01);
 
-      userEvent.click(toAccount);
-      userEvent.click(getByRole('option', { name: /staff savings/i }));
+      expect(
+        await findByText(
+          'Amount cannot exceed the available balance of $15,000.00',
+        ),
+      ).toBeInTheDocument();
+
+      // user-event refuses to click a disabled button, so the disabled
+      // assertion above is what guarantees no mutation can fire.
+      await waitFor(() =>
+        expect(getByRole('button', { name: /submit/i })).toBeDisabled(),
+      );
 
-      const amount = getByRole('spinbutton', { name: /amount/i });
+      expect(mutationSpy).not.toHaveGraphqlOperation('CreateTransfer');
+    });
 
-      userEvent.clear(amount);
-      userEvent.type(amount, '20000');
-      userEvent.tab();
+    it('should allow a transfer of exactly the full available balance', async () => {
+      const result = render(<Components />);
+      const { getByRole } = result;
+
+      enterTransferDetails(result, '15000');
+
+      userEvent.click(getByRole('button', { name: /submit/i }));
+
+      await waitFor(() =>
+        expect(mutationSpy).toHaveGraphqlOperation('CreateTransfer', {
+          amount: 15000,
+          sourceFundTypeName: 'Staff Account',
+        }),
+      );
+    });
+
+    it('should still block below a zero balance even when the fund has a deficit limit', async () => {
+      // Per MPDX-10004 the floor is $0 regardless of the fund's deficit
+      // limit. If the rule loosens to allow a deficit, this is the test to
+      // update.
+      const fundsWithDeficit = [
+        { ...fundsMock[0], deficitLimit: -1000 },
+        fundsMock[1],
+      ];
+
+      const result = render(<Components funds={fundsWithDeficit} />);
+      const { getByRole, findByText } = result;
+
+      enterTransferDetails(result, '15500');
 
-      const alert = await findByRole('alert');
-      expect(alert).toBeInTheDocument();
       expect(
-        within(alert).getByText(
-          /this amount will cause your account balance to exceed the deficit limit/i,
+        await findByText(
+          'Amount cannot exceed the available balance of $15,000.00',
         ),
       ).toBeInTheDocument();
+
+      await waitFor(() =>
+        expect(getByRole('button', { name: /submit/i })).toBeDisabled(),
+      );
+    });
+
+    it('should allow winding down a recurring transfer whose amount exceeds the balance', async () => {
+      const overBalanceTransfer: TransferModalData['transfer'] = {
+        id: 'transfer-id',
+        transferFrom: 'Staff Account',
+        transferTo: 'Staff Savings',
+        amount: 20000,
+        schedule: ScheduleEnum.Monthly,
+        transferDate: DateTime.fromISO('2024-11-01'),
+        endDate: null,
+        note: '',
+        recurringId: 'recurring-id',
+      };
+
+      const { getByRole, getByLabelText } = render(
+        <Components
+          transfer={overBalanceTransfer}
+          type={TransferTypeEnum.Edit}
+        />,
+      );
+
+      const endDate = getByLabelText(/end date/i);
+      userEvent.type(endDate, '12/01/2025');
+      userEvent.tab();
+
+      userEvent.click(getByRole('button', { name: /submit/i }));
+
+      await waitFor(() =>
+        expect(mutationSpy).toHaveGraphqlOperation('UpdateRecurringTransfer', {
+          id: 'recurring-id',
+          amount: 20000,
+        }),
+      );
+    });
+
+    it('should warn but still allow increasing a transfer beyond the available balance when editing', async () => {
+      const transfer: TransferModalData['transfer'] = {
+        id: 'transfer-id',
+        transferFrom: 'Staff Account',
+        transferTo: 'Staff Savings',
+        amount: 500,
+        schedule: ScheduleEnum.Monthly,
+        transferDate: DateTime.fromISO('2024-11-01'),
+        endDate: null,
+        note: '',
+        recurringId: 'recurring-id',
+      };
+
+      const { getByRole, findByRole } = render(
+        <Components transfer={transfer} type={TransferTypeEnum.Edit} />,
+      );
+
+      const amountField = getByRole('spinbutton', { name: /amount/i });
+      userEvent.clear(amountField);
+      userEvent.type(amountField, '16000');
+      userEvent.tab();
+
+      const alert = await findByRole('alert');
+      expect(alert).toHaveTextContent(
+        /greater than your Staff Account account's available balance/i,
+      );
+      expect(alert).toHaveTextContent('-$1,000.00');
+
+      userEvent.click(getByRole('button', { name: /submit/i }));
+
+      await waitFor(() =>
+        expect(mutationSpy).toHaveGraphqlOperation('UpdateRecurringTransfer', {
+          id: 'recurring-id',
+          amount: 16000,
+        }),
+      );
+    });
+
+    it('should warn but still allow a new recurring transfer over the available balance', async () => {
+      const { getByRole, getByLabelText, findByRole } = render(<Components />);
+
+      userEvent.click(getByRole('combobox', { name: /to account/i }));
+      userEvent.click(getByRole('option', { name: /staff savings/i }));
+
+      const amountField = getByRole('spinbutton', { name: /amount/i });
+      userEvent.clear(amountField);
+      userEvent.type(amountField, '20000');
+
+      userEvent.click(getByRole('radio', { name: /monthly/i }));
+
+      const transferDate = getByLabelText(/transfer date/i);
+      userEvent.clear(transferDate);
+      userEvent.type(transferDate, '12/01/2024');
+      userEvent.tab();
+
+      const alert = await findByRole('alert');
+      expect(alert).toHaveTextContent('-$5,000.00');
+
+      userEvent.click(getByRole('button', { name: /submit/i }));
+
+      await waitFor(() =>
+        expect(mutationSpy).toHaveGraphqlOperation('CreateRecurringTransfer', {
+          amount: 20000,
+          sourceFundTypeName: 'Staff Account',
+        }),
+      );
     });
 
     it('should show proper currency symbol in amount field', () => {
@@ -822,8 +981,8 @@ describe('TransferModal', () => {
     it('should update a transfer', async () => {
       const dataWithValues: TransferModalData['transfer'] = {
         id: 'transfer-id',
-        transferFrom: 'Primary',
-        transferTo: 'Savings',
+        transferFrom: 'Staff Account',
+        transferTo: 'Staff Savings',
         amount: 500,
         schedule: ScheduleEnum.Monthly,
         transferDate: DateTime.fromISO('2024-11-01'),
diff --git a/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.tsx b/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.tsx
index 3ddd2cf9c..39fc47719 100644
--- a/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.tsx
+++ b/src/components/HrTools/SavingsFundTransfer/TransferModal/TransferModal.tsx
@@ -34,6 +34,7 @@ import {
   dateFormat,
   dateFormatShort,
 } from 'src/lib/intlFormat';
+import { availableBalance, toCents } from '../Helper/availableBalance';
 import { FundFieldsFragment } from '../ReportsSavingsFund.generated';
 import {
   useCreateRecurringTransferMutation,
@@ -92,7 +93,7 @@ const pastDateMessage = (schedule: ScheduleEnum): string =>
     ? i18n.t('Transfer date cannot be in the past')
     : i18n.t('Recurring transfers must start at least one day in the future');
 
-const transferSchema = (locale: string) =>
+const transferSchema = (locale: string, funds: FundFieldsFragment[]) =>
   yup.object({
     transferFrom: yup.string().required(i18n.t('From account is required')),
     transferTo: yup.string().required(i18n.t('To account is required')),
@@ -156,7 +157,47 @@ const transferSchema = (locale: string) =>
     amount: yup
       .number()
       .required(i18n.t('Amount is required'))
-      .min(0.01, i18n.t('Amount must be at least $0.01')),
+      .min(0.01, i18n.t('Amount must be at least $0.01'))
+      .test('within-available-balance', function (value) {
+        const { transferFrom, schedule, isEditing } = this.parent as {
+          transferFrom?: string;
+          schedule?: ScheduleEnum;
+          isEditing?: boolean;
+        };
+        if (typeof value !== 'number') {
+          return true;
+        }
+        // Only a new one-time transfer debits the account immediately, so
+        // only it is hard-blocked (MPDX-10004). A recurring setup's payments
+        // happen in the future against future balances — the form shows a
+        // non-blocking warning instead, and each payment is enforced when it
+        // is processed.
+        if (schedule !== ScheduleEnum.OneTime || isEditing) {
+          return true;
+        }
+        const fund = funds.find((fund) => fund.fundType === transferFrom);
+        if (!fund) {
+          return this.createError({
+            message: i18n.t(
+              'Unable to verify the available balance for this account',
+            ),
+          });
+        }
+        const available = availableBalance(fund);
+        if (toCents(value) <= toCents(available)) {
+          return true;
+        }
+        return this.createError({
+          message: i18n.t(
+            'Amount cannot exceed the available balance of {{balance}}',
+            {
+              balance: currencyFormat(Math.max(available, 0), 'USD', locale, {
+                showTrailingZeros: true,
+              }),
+            },
+          ),
+        });
+      }),
     note: yup.string().when('schedule', {
       is: ScheduleEnum.OneTime,
       then: (schema) => schema.trim().required(i18n.t('Note is required')),
@@ -291,7 +332,7 @@ export const TransferModal: React.FC<TransferModalProps> = ({
           isEditing: Boolean(data.transfer.id),
           originalStart: data.transfer.transferDate ?? null,
         }}
-        validationSchema={transferSchema(locale)}
+        validationSchema={transferSchema(locale, funds)}
         onSubmit={handleSubmit}
       >
         {({
@@ -320,11 +361,15 @@ export const TransferModal: React.FC<TransferModalProps> = ({
           const locale = useLocale();
 
           const fund = funds.find((f) => f.fundType === transferFrom);
+          // New one-time transfers over the balance are hard-blocked by the
+          // schema; recurring setups and edits only warn, since their
+          // payments process in the future against future balances.
           const projected = fund ? fund.endBalance - amount : null;
-          const showAlert =
+          const showOverdraftWarning =
             !!fund &&
             projected !== null &&
-            projected < -(fund.deficitLimit ?? 0);
+            !(isNew && schedule === ScheduleEnum.OneTime) &&
+            toCents(amount) > toCents(availableBalance(fund));
 
           return (
             <form onSubmit={handleSubmit} noValidate>
@@ -621,22 +666,22 @@ export const TransferModal: React.FC<TransferModalProps> = ({
                   </Box>
                 )}
 
-                {showAlert && (
+                {showOverdraftWarning && (
                   <Alert severity="warning">
                     {t(
-                      "This amount will cause your account balance to exceed the deficit limit. If you proceed, your {{ fund }} account's projected balance will be ",
+                      "This amount is greater than your {{ fund }} account's available balance. If you proceed, the account's projected balance will be ",
                       {
                         fund: fund.fundType,
                       },
                     )}
                     <strong>
-                      {t('{{ projected }}', {
-                        projected: currencyFormat(projected, 'USD', locale, {
-                          showTrailingZeros: true,
-                        }),
+                      {currencyFormat(projected, 'USD', locale, {
+                        showTrailingZeros: true,
                       })}
                     </strong>
-                    {t(' after the first scheduled payment is processed.')}
+                    {t(
+                      ' after the first scheduled payment is processed. Payments that would cause a negative balance may not be processed.',
+                    )}
                   </Alert>
                 )}
               </DialogContent>