feat(component): WalletCard — Credit Balance Display

[bntvllnt]

Summary

Credit wallet balance display with threshold-based warnings, reload CTA, and sync recovery. Handles three states: balance with amount, empty wallet, and unlimited/exempt. The primary wallet component for prepaid credit SaaS models.

Proposed API

<WalletCard
  balanceCents={2350}
  currency="EUR"
  thresholds={{ critical: 100, low: 500 }}
  onReload={handleReload}
  onSync={handleSync}
/>

// Empty wallet
<WalletCard
  balanceCents={0}
  currency="EUR"
  onReload={handleReload}
  onSync={handleSync}
  emptyMessage="Add credits to start using AI features."
/>

// Unlimited / exempt
<WalletCard variant="unlimited" label="VIP/Admin accounts bypass credit requirements" />

Requirements

• Three states: balance, empty, unlimited
• Balance state: large formatted amount + threshold color (neutral/yellow/red)
• Critical threshold: red amount + "Balance critically low!" warning
• Low threshold: yellow amount + "Balance is low" warning
• Empty state: zero amount + contextual message + reload CTA
• Unlimited state: amber "Unlimited" display + exempt message
• Configurable thresholds { low: number; critical: number } in cents
• Locale-aware currency formatting (Intl.NumberFormat)
• Reload CTA slot — accepts any button/link component
• Sync recovery: "Paid but not showing? Sync to recover" with loading/success/error feedback
• Section label: "Credit balance" uppercase tracking
• Dark mode: semi-transparent card backgrounds
• Accessible: balance state communicated via aria-live for screen readers

Visual States

┌──────────────────────────────────────────────────┐
│  HEALTHY BALANCE                                 │
│  ┌────────────────────────────────────────────┐  │
│  │ CREDIT BALANCE                             │  │
│  │ €23.50                    (neutral text)   │  │
│  │                                            │  │
│  │ [Reload credits]                           │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  LOW BALANCE                                     │
│  ┌────────────────────────────────────────────┐  │
│  │ CREDIT BALANCE                             │  │
│  │ €4.20                    (yellow text)     │  │
│  │ Balance is low. Consider reloading.        │  │
│  │ [Reload credits]                           │  │
│  └────────────────────────────────────────────┘  │
│                                                  │
│  CRITICAL                                        │
│  ┌────────────────────────────────────────────┐  │
│  │ CREDIT BALANCE                             │  │
│  │ €0.50                    (red text)        │  │
│  │ Balance critically low! Reload now.        │  │
│  │ [Reload credits]                           │  │
│  └────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────┘

Use Cases

• SaaS billing page credit wallet
• API platform credit balance display
• Cloud compute credits remaining
• Gaming platform in-app currency wallet

Composes

• Card, Button

Origin

Extracted from WalletBalance, WalletWithBalance, EmptyWallet, SyncCreditsButton in apps/web-ai-os/app/account/billing/billing-client.tsx in vllnt/vllnt monorepo.