feat: standardize currency display across platform

[abbakargarba]

closes #436

Title

feat: implement global currency formatting utility for standardized monetary display

---

Overview

This PR introduces a global currency formatting utility to standardize how money is displayed across the platform, securely converting backend bigint kobo values into displayable currency values.

It centralizes formatting logic, improves consistency across dashboards and financial views, and supports localized formatting using Intl.NumberFormat.

---

🚀 Implementation Approach

Key Changes

Global formatCurrency Utility

Created:

src/utils/formatters.ts

Features:

• Uses Intl.NumberFormat for localized formatting

• Converts kobo → NGN by dividing by 100

• Supports multiple currencies:

  • NGN
  • USD
  • EUR
  • Extendable for others

Example output:

₦1,500.00

---

Graceful Value Handling

Safely handles:

• null
• undefined
• invalid values

Includes fallback behavior to prevent UI failures.

---

Updated Components

Integrated the formatter across 6 component files:

Finance

• NairaTransactionHistory.tsx

---

Payroll

• PayoutHistory.tsx

---

Invoices

• invoices/page.tsx
• invoices/[id]/page.tsx
• InvoiceSummary.tsx
• InvoiceDetailsSection.tsx

---

🧪 Testing

Added:

src/utils/formatters.test.ts

Includes unit coverage for:

• Kobo conversion
• Decimal placement
• Thousands separators
• Currency symbols
• Invalid input handling
• Multi-currency formatting

---

🔧 Technical Details

Backend Integration

Safely converts:

bigint (kobo) → formatted NGN display

---

Localization

Uses:

Intl.NumberFormat

with proper locale-aware formatting.

---

Type Safety

• Full TypeScript support
• Typed interfaces for formatting options
• Safe parameter handling

---

Error Handling

• Graceful fallback for invalid values
• Prevents runtime formatting failures

---

Consistency

All monetary displays now use a single formatting standard.

---

📁 Files Changed

New Files

• src/utils/formatters.ts
• src/utils/formatters.test.ts

---

Updated Files

• src/app/(dashboard)/invoices/[id]/page.tsx
• src/app/(dashboard)/invoices/page.tsx
• src/app/(dashboard)/payroll/components/PayoutHistory.tsx
• src/components/features/finance/NairaTransactionHistory.tsx
• src/components/features/invoices/InvoiceSummary.tsx
• src/components/features/invoices/InvoiceDetailsSection.tsx

---

✅ What Done Looks Like

• ✅ Currency values formatted safely across dashboards, invoices, and payroll
• ✅ Commas and decimals rendered consistently
• ✅ Backend kobo values converted correctly to NGN display
• ✅ Localized formatting via Intl.NumberFormat
• ✅ Production-ready with comprehensive test coverage

---

📋 Testing Results

• ✅ Unit tests pass for all formatting scenarios
• ✅ TypeScript compiles with no errors
• ✅ Existing functionality preserved
• ✅ Backward compatibility maintained

---

📈 Impact

• Consistency: One standard for all currency rendering
• Accuracy: Prevents incorrect kobo-to-naira display
• Maintainability: Centralized formatting logic reduces duplication
• Localization: Supports future multi-currency expansion
• Reliability: Handles invalid or missing values safely

---

⚠️ Breaking Changes

None — fully backward compatible.

---

🌿 Branch

Source:
feature/Fix-and-Standardize-Currency-Display

Target:
dev

---

✅ Checklist

• ✅ Global formatter implemented
• ✅ All target components updated
• ✅ Tests added and passing
• ✅ Type safety maintained
• ✅ Localization supported
• ✅ Backward compatibility preserved
• ✅ Ready for review

[vercel]

@abbakargarba is attempting to deploy a commit to the vestroll's projects Team on Vercel.

A member of the Team first needs to authorize it.

[codeZe-us]

@abbakargarba Good work

[abbakargarba]

@abbakargarba Good work

thank you boss