@birhaus/financial/README.md

Financial components and utilities for BIRHAUS design system - SEPRELAD compliant

# @birhaus/financial

**SEPRELAD-compliant financial components for BIRHAUS design system**

[![npm version](https://badge.fury.io/js/@birhaus%2Ffinancial.svg)](https://badge.fury.io/js/@birhaus%2Ffinancial)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
[![Spanish-First](https://img.shields.io/badge/Spanish--First-✓-green.svg)](#spanish-first-design)
[![SEPRELAD](https://img.shields.io/badge/SEPRELAD-Compliant-yellow.svg)](#seprelad-compliance)

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

```bash
npm install @birhaus/financial

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

## 🎯 Quick Start

```tsx
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:

```tsx
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

```tsx
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

```tsx
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

```tsx
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

```tsx
// 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

```tsx
<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:

```tsx
// 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:

```tsx
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:

```tsx
// 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

```tsx
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

```tsx
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**
```bash
# 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**
```tsx
// Ensure proper locale setup
import { BirhausProvider } from '@birhaus/provider'

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

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

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md).

### Development Setup

```bash
# 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.**