@birhaus/financial

SEPRELAD-compliant financial components for BIRHAUS design system

Comprehensive React components for financial applications with built-in compliance for Paraguay's financial regulations (SEPRELAD), Spanish-first internationalization, and BIRHAUS UX principles.

🚀 Features

• 💰 Multi-Currency Support - PYG (₲), USD ($), EUR (€), BRL (R$), ARS ($)
• 🏛️ SEPRELAD Compliance - Automatic reporting and audit trails for financial regulations
• 🇪🇸 Spanish-First - Primary Spanish interface with English fallback
• 📊 Financial Analytics - Built-in KPI tracking and trend analysis
• 🔒 Security-First - Privacy controls and sensitive data protection
• ♿ Accessibility - WCAG AA+ compliant components
• 📱 Responsive - Mobile-optimized financial interfaces
• 🎨 BIRHAUS UX - Cognitive load reduction and undo patterns

📦 Installation

npm install @birhaus/financial

# Peer dependencies
npm install react react-dom @birhaus/tokens @birhaus/primitives @birhaus/provider

🎯 Quick Start

import { 
  BirhausCurrencyDisplay, 
  BirhausTransactionList, 
  BirhausAccountSummary,
  BirhausInvestmentPortfolio 
} from '@birhaus/financial'

function FinancialDashboard() {
  return (
    <div>
      {/* Currency Display with Guaraníes support */}
      <BirhausCurrencyDisplay 
        amount={1500000}
        currency="PYG"
        showSymbol={true}
      />
      
      {/* Transaction Management */}
      <BirhausTransactionList 
        transactions={transactionData}
        showFilters={true}
        showSearch={true}
        onExport={handleExport}
      />
      
      {/* Account Overview */}
      <BirhausAccountSummary 
        accounts={accountData}
        showBalances={true}
        onAccountClick={handleAccountClick}
      />
    </div>
  )
}

📋 Components

Core Components

| Component | Description | Key Features | |-----------|-------------|--------------| | BirhausCurrencyDisplay | Multi-currency formatting | PYG/USD/EUR support, locale-aware | | BirhausTransactionList | Transaction management | Filtering, search, SEPRELAD compliance | | BirhausAccountSummary | Account overview | Balance tracking, multiple account types | | BirhausFinancialMetricCard | KPI display cards | Trend indicators, goal tracking | | BirhausPaymentForm | Payment processing | Validation, method selection | | BirhausBudgetTracker | Budget management | Progress tracking, alerts | | BirhausInvestmentPortfolio | Investment tracking | Performance metrics, risk analysis |

Hooks

| Hook | Purpose | Returns | |------|---------|---------| | useCurrency | Currency operations | Format, parse, convert, validate | | useTransactions | Transaction management | CRUD operations, filtering, analytics | | useFinancialMetrics | KPI calculations | Real-time metrics, trend analysis |

🏛️ SEPRELAD Compliance

This package automatically handles Paraguay's financial reporting requirements:

import { checkSEPRELADCompliance } from '@birhaus/financial'

// Automatic compliance checking
const transaction = {
  monto: 15000, // USD
  moneda: 'USD',
  tipo: 'transferencia'
}

const compliance = checkSEPRELADCompliance(transaction)
if (compliance.requiresReport) {
  // Automatic reporting triggered
  console.log('SEPRELAD report required:', compliance.reportDetails)
}

Compliance Features

• ✅ Threshold Monitoring - Automatic detection of reportable amounts
• ✅ Audit Trails - Complete transaction logging
• ✅ Report Generation - Automated SEPRELAD report creation
• ✅ Documentation - Spanish-language compliance documentation
• ✅ Real-time Alerts - Compliance violation warnings

💱 Currency Support

Supported Currencies

| Code | Symbol | Name (Spanish) | Name (English) | Decimals | |------|--------|---------------|----------------|----------| | PYG | ₲ | Guaraníes | Paraguayan Guarani | 0 | | USD | $ | Dólares | US Dollar | 2 | | EUR | € | Euros | Euro | 2 | | BRL | R$ | Reales | Brazilian Real | 2 | | ARS | $ | Pesos Argentinos | Argentine Peso | 2 |

Currency Utilities

import { useCurrency } from '@birhaus/financial'

function CurrencyExample() {
  const { 
    formatCurrency, 
    parseCurrency, 
    convertCurrency,
    validateAmount 
  } = useCurrency()
  
  // Format for display
  const formatted = formatCurrency(1500000, { currency: 'PYG', showSymbol: true })
  // Result: "₲ 1.500.000"
  
  // Parse user input
  const parsed = parseCurrency("₲ 1.500.000")
  // Result: 1500000
  
  // Convert between currencies
  const converted = await convertCurrency(1500000, 'PYG', 'USD')
  
  // Validate amounts
  const validation = validateAmount(1500000, 'PYG')
  // Result: { valid: true, errors: [], warnings: [] }
  
  return <div>{formatted}</div>
}

📊 Financial Analytics

KPI Tracking

import { useFinancialMetrics, BirhausFinancialMetricCard } from '@birhaus/financial'

function MetricsDashboard() {
  const { metrics, loading, error } = useFinancialMetrics(accounts, transactions, budgets)
  
  return (
    <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
      {metrics.map(metric => (
        <BirhausFinancialMetricCard
          key={metric.id}
          metric={metric}
          showTrend={true}
          showTarget={true}
          allowPrivacyToggle={true}
        />
      ))}
    </div>
  )
}

Built-in Metrics

• 💰 Total Balance - Account balances across currencies
• 📈 Income Trends - Period-over-period income analysis
• 📉 Expense Tracking - Spending patterns and categorization
• 🎯 Budget Adherence - Budget vs actual spending
• 💳 Available Credit - Credit utilization and limits
• 📊 Investment Performance - Portfolio tracking and ROI

🔒 Privacy & Security

Privacy Controls

import { BirhausInvestmentPortfolio } from '@birhaus/financial'

<BirhausInvestmentPortfolio
  investments={portfolioData}
  showPrivacyToggle={true} // Users can hide sensitive values
  showPerformanceMetrics={true}
/>

Security Features

• 🔐 Data Masking - Optional hiding of sensitive financial data
• 🛡️ Input Validation - Comprehensive validation for all financial inputs
• 🔍 Audit Logging - Complete audit trails for compliance
• ⚠️ Fraud Detection - Pattern recognition for suspicious transactions
• 🚨 Real-time Alerts - Immediate notifications for policy violations

🇪🇸 Spanish-First Design

All components prioritize Spanish language and Paraguay-specific patterns:

Terminology

| Spanish | English | Usage | |---------|---------|-------| | Saldo | Balance | Account balance | | Transferencia | Transfer | Money transfer | | Inversión | Investment | Investment transaction | | Presupuesto | Budget | Budget/spending plan | | Rendimiento | Performance | Investment returns | | Cumplimiento | Compliance | Regulatory compliance |

Example Usage

// Spanish-first with English fallback
<BirhausTransactionList
  transactions={transactions}
  emptyMessage="No hay transacciones que mostrar"
  searchPlaceholder="Buscar transacciones..."
  filters={{
    tipo: ['ingreso', 'gasto', 'transferencia'],
    estado: ['completada', 'pendiente']
  }}
/>

🎨 BIRHAUS UX Principles

Cognitive Load Reduction

• 4-3-1 Rule - Maximum 4 nav items, 3 actions, 1 primary action per screen
• Miller's Law - Lists limited to 7±2 items with pagination
• Progressive Disclosure - Complex data revealed gradually
• Undo Patterns - No confirmation dialogs, undo actions instead

Example: Transaction List with BIRHAUS UX

<BirhausTransactionList
  transactions={transactions}
  maxItems={7} // Miller's Law compliance
  showFilters={true} // Progressive disclosure
  onTransactionClick={handleClick} // No confirmation dialogs
  // Undo system available through context
/>

📱 Responsive Design

All components are mobile-optimized:

// Automatic responsive behavior
<BirhausAccountSummary
  accounts={accounts}
  showBalances={true}
  // Automatically stacks on mobile
  // Touch-friendly interactions
  // Optimized for small screens
/>

🧪 TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { 
  Transaction, 
  Investment, 
  CurrencyCode,
  TransactionType,
  InvestmentRisk 
} from '@birhaus/financial'

const transaction: Transaction = {
  id: '123',
  tipo: 'ingreso',
  monto: 500000,
  moneda: 'PYG',
  categoria: 'salario',
  descripcionEs: 'Salario mensual',
  fecha: new Date(),
  estado: 'completada'
}

🔄 Migration from v1.0.3

Version 1.0.4 includes TypeScript fixes and enhanced type safety:

// Before v1.0.4 - potential type issues
const investment = {
  nombre: 'Tesla Stock', // Now deprecated
  // Missing required properties
}

// After v1.0.4 - comprehensive typing
const investment: Investment = {
  id: '1',
  nombreEs: 'Acciones Tesla', // Spanish-first
  nombreEn: 'Tesla Stock',
  tipo: 'acciones',
  montoInvertido: 50000,
  valorActual: 55000,
  moneda: 'USD',
  fechaInversion: new Date(),
  rendimiento: 10,
  riesgo: 'medio',
  liquidez: 'alta',
  // Enhanced properties
  costoBase: 50000,
  cantidad: 100,
  simbolo: 'TSLA'
}

📚 Advanced Usage

Custom Financial Metrics

import { useFinancialMetrics } from '@birhaus/financial'

function CustomMetrics() {
  const { 
    metrics, 
    calculateMetrics,
    exportMetrics,
    financialHealthScore 
  } = useFinancialMetrics(accounts, transactions, budgets)
  
  // Custom calculations
  const customMetric = {
    id: 'custom-roi',
    tipo: 'objetivo',
    nombreEs: 'ROI Personalizado',
    valor: calculateCustomROI(investments),
    tendencia: calculateTrend(historicalData)
  }
  
  return (
    <div>
      <h3>Puntuación de Salud Financiera: {financialHealthScore}/100</h3>
      <button onClick={exportMetrics}>
        Exportar Métricas
      </button>
    </div>
  )
}

SEPRELAD Integration

import { useSEPRELADCompliance } from '@birhaus/financial'

function ComplianceMonitor() {
  const { 
    checkCompliance,
    generateReport,
    getViolations 
  } = useSEPRELADCompliance()
  
  const handleLargeTransaction = async (transaction: Transaction) => {
    const compliance = await checkCompliance(transaction)
    
    if (compliance.requiresReport) {
      const report = await generateReport(transaction)
      console.log('SEPRELAD report generated:', report.id)
    }
  }
  
  return <ComplianceMonitor />
}

🐛 Troubleshooting

Common Issues

TypeScript Errors

# Ensure you have the latest version
npm install @birhaus/financial@latest

# Clear TypeScript cache
rm -rf node_modules/.cache
npx tsc --build --clean

Currency Formatting Issues

// Ensure proper locale setup
import { BirhausProvider } from '@birhaus/provider'

<BirhausProvider language="es" locale="es-PY">
  <App />
</BirhausProvider>

SEPRELAD Compliance Warnings

// Check your transaction amounts
const isReportable = amount >= 10000 // USD equivalent
if (isReportable) {
  // Handle SEPRELAD reporting
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Development Setup

# Clone and install
git clone https://github.com/birhaus/components
cd packages/financial
npm install

# Development
npm run dev

# Build
npm run build

# Test
npm run test

📊 Performance

• Bundle Size: ~140KB (ESM), ~156KB (CJS)
• TypeScript: Full declarations included
• Tree Shaking: Optimized for minimal bundle impact
• Loading: Async currency conversion API calls
• Caching: Automatic exchange rate caching

📄 License

MIT © BIRHAUS Team

Made with ❤️ for the Spanish-speaking financial community in Paraguay and Latin America.