fix(ui): locale-aware negative amount formatting

.changeset/sixty-hairs-sniff.md

@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Use locale and currency aware formatting for negative money amounts

packages/ui/src/components/Checkout/CheckoutForm.tsx

@@ -10,6 +10,7 @@ import { SegmentedControl } from '@/ui/elements/SegmentedControl';
 import { Select, SelectButton, SelectOptionList } from '@/ui/elements/Select';
 import { DevModeOverlay } from '@/ui/elements/DevModeNotice';
 import { Tooltip } from '@/ui/elements/Tooltip';
+import { toNegativeAmount } from '@/ui/utils/billing';
 import {
   getCheckoutSeatUnitTotal,
   getIncludedSeatsUnitTotalTier,
@@ -134,23 +135,25 @@ export const CheckoutForm = withCardStateProvider(() => {
             <LineItems.Group variant='tertiary'>
               <LineItems.Title title={localizationKeys('billing.proratedDiscount')} />
               <LineItems.Description
-                text={totals.discounts?.proration?.amount ? `- ${$(totals.discounts.proration.amount)}` : ''}
+                text={totals.discounts?.proration?.amount ? $(toNegativeAmount(totals.discounts.proration.amount)) : ''}
               />
             </LineItems.Group>
           )}
           {showProratedCredit && (
             <LineItems.Group variant='tertiary'>
               <LineItems.Title title={localizationKeys('billing.creditRemainder')} />
               <LineItems.Description
-                text={totals.credits?.proration?.amount ? `- ${$(totals.credits.proration.amount)}` : ''}
+                text={totals.credits?.proration?.amount ? $(toNegativeAmount(totals.credits.proration.amount)) : ''}
               />
             </LineItems.Group>
           )}
           {showAccountCredits && (
             <LineItems.Group variant='tertiary'>
               <LineItems.Title title={localizationKeys('billing.payerCreditRemainder')} />
               <LineItems.Description
-                text={totals.credits?.payer?.appliedAmount ? `- ${$(totals.credits.payer.appliedAmount)}` : ''}
+                text={
+                  totals.credits?.payer?.appliedAmount ? $(toNegativeAmount(totals.credits.payer.appliedAmount)) : ''
+                }
               />
             </LineItems.Group>
           )}

packages/ui/src/components/Checkout/__tests__/Checkout.test.tsx

@@ -446,8 +446,8 @@ describe('Checkout', () => {
     expect(prorationCreditRow).toBeInTheDocument();
     expect(accountCreditRow).toBeInTheDocument();
 
-    expect(prorationCreditRow).toHaveTextContent('- $5.00');
-    expect(accountCreditRow).toHaveTextContent('- $10.00');
+    expect(prorationCreditRow).toHaveTextContent('-$5.00');
+    expect(accountCreditRow).toHaveTextContent('-$10.00');
   });
 
   it('renders free trial details during confirmation stage', async () => {
@@ -1738,7 +1738,7 @@ describe('Checkout', () => {
 
       const proratedDiscountRow = getByText('Prorated discount').closest('.cl-lineItemsGroup');
       expect(proratedDiscountRow).toBeInTheDocument();
-      expect(proratedDiscountRow).toHaveTextContent('- $5.00');
+      expect(proratedDiscountRow).toHaveTextContent('-$5.00');
 
       const totalPerPeriodRow = getByText('Total per period').closest('.cl-lineItemsGroup');
       expect(totalPerPeriodRow).toBeInTheDocument();

packages/ui/src/components/PaymentAttempts/PaymentAttemptPage.tsx

@@ -5,6 +5,7 @@ import { Alert } from '@/ui/elements/Alert';
 import { Header } from '@/ui/elements/Header';
 import { LineItems } from '@/ui/elements/LineItems';
 import { ProfileCard } from '@/ui/elements/ProfileCard';
+import { toNegativeAmount } from '@/ui/utils/billing';
 import { getPlanSeatLimit, getSeatsPerUnitTotal, summarizeSeatCharges } from '@/ui/utils/billingPlanSeats';
 import { formatDate } from '@/ui/utils/formatDate';
 import { truncateWithEndVisible } from '@/ui/utils/truncateTextWithEndVisible';
@@ -281,23 +282,23 @@ function PaymentAttemptBody({ paymentAttempt }: { paymentAttempt: BillingPayment
         {paymentAttempt.totals?.discounts?.proration && paymentAttempt.totals.discounts.proration.amount.amount > 0 && (
           <LineItems.Group variant='tertiary'>
             <LineItems.Title title={localizationKeys('billing.proratedDiscount')} />
-            <LineItems.Description text={`- ${$(paymentAttempt.totals.discounts.proration.amount)}`} />
+            <LineItems.Description text={$(toNegativeAmount(paymentAttempt.totals.discounts.proration.amount))} />
           </LineItems.Group>
         )}
         {subscriptionItem.credits &&
           subscriptionItem.credits.proration &&
           subscriptionItem.credits.proration.amount.amount > 0 && (
             <LineItems.Group variant='tertiary'>
               <LineItems.Title title={localizationKeys('billing.prorationCredit')} />
-              <LineItems.Description text={`- ${$(subscriptionItem.credits.proration.amount)}`} />
+              <LineItems.Description text={$(toNegativeAmount(subscriptionItem.credits.proration.amount))} />
             </LineItems.Group>
           )}
         {subscriptionItem.credits &&
           subscriptionItem.credits.payer &&
           subscriptionItem.credits.payer.appliedAmount.amount > 0 && (
             <LineItems.Group variant='tertiary'>
               <LineItems.Title title={localizationKeys('billing.accountCredit')} />
-              <LineItems.Description text={`- ${$(subscriptionItem.credits.payer.appliedAmount)}`} />
+              <LineItems.Description text={$(toNegativeAmount(subscriptionItem.credits.payer.appliedAmount))} />
             </LineItems.Group>
           )}
       </LineItems.Root>

packages/ui/src/utils/__tests__/billing.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+
+import { toNegativeAmount } from '../billing';
+
+describe('toNegativeAmount', () => {
+  it('converts positive amounts to negative', () => {
+    const amount = {
+      amount: 100,
+      amountFormatted: '1.00',
+      currency: 'usd',
+      currencySymbol: '$',
+    };
+    expect(toNegativeAmount(amount)).toStrictEqual({
+      amount: -100,
+      amountFormatted: '-1.00',
+      currency: 'usd',
+      currencySymbol: '$',
+    });
+  });
+
+  it('retains negative amounts', () => {
+    const amount = {
+      amount: -100,
+      amountFormatted: '-1.00',
+      currency: 'usd',
+      currencySymbol: '$',
+    };
+    expect(toNegativeAmount(amount)).toStrictEqual({
+      amount: -100,
+      amountFormatted: '-1.00',
+      currency: 'usd',
+      currencySymbol: '$',
+    });
+  });
+});

packages/ui/src/utils/billing.ts

@@ -0,0 +1,18 @@
+import type { BillingMoneyAmount } from '@clerk/shared/types/billing';
+
+/**
+ * Given a BillingMoneyAmount, convert positive values to negative. If the amount is already negative, leave it alone.
+ */
+export function toNegativeAmount(amount: BillingMoneyAmount): BillingMoneyAmount {
+  if (amount.amount < 0) {
+    return amount;
+  }
+
+  return {
+    ...amount,
+    // convert positive amounts to negative
+    amount: -amount.amount,
+    // naively converts amountFormatted
+    amountFormatted: `-${amount.amountFormatted}`,
+  };
+}