Cash Balance Card

Cash Balance Card

Component File: src/features/dashboard/components/FundSummaryCard.tsx Access Level: All authenticated users Last Updated: January 29, 2026 Status: ✅ Implemented

---

Overview

The Cash Balance Card is an addable dashboard component that displays the organization's current cash balance (sum of bank/cash accounts from balance sheet) with a year-over-year comparison and traffic light indicator showing financial health status.

UI Features

Main Display

• Title: "Cash Balance"
• Primary Value: Current cash balance (sum of cash/bank asset accounts)
• Traffic Light Indicator: Colored dot/badge showing status (green/yellow/red)
• Percentage Change: YoY comparison with trend arrow
• Subtitle: "As of {date}" showing the as-of date
• Clickable Jumpoff: Links to Balance Sheet report

Traffic Light Logic

| Status | Condition | Color | CSS Classes |

|--------|-----------|-------|-------------|

| 🟢 **On Track** | Current ≥ 90% of Last Year | Green | `text-green-600 dark:text-green-400 bg-green-50 dark:bg-green-950` |

| 🟡 **Caution** | Current is 70-90% of Last Year | Yellow/Amber | `text-amber-600 dark:text-amber-400 bg-amber-50 dark:bg-amber-950` |

| 🔴 **Behind** | Current < 70% of Last Year | Red | `text-red-600 dark:text-red-400 bg-red-50 dark:bg-red-950` |

| ⚪ **Neutral** | Both periods = 0 | Gray | `text-muted-foreground bg-muted` |

Special Cases

• If last year = 0 and current > 0 → Green (improvement)
• If both = 0 → Neutral (gray)
• If current < 0 (negative cash) → Red regardless of comparison

Clickable Jumpoff

When the user clicks the "View Balance Sheet" link:

navigateTo('reports', 'balance-sheet');

Data Requirements

FundSummaryData Interface

interface FundSummaryData {
  currentNetIncome: number;      // Current cash balance (field name kept for backward compat)
  previousNetIncome: number;     // Cash balance same date last year
  percentChange: number;         // YoY percentage change
  status: 'ahead' | 'on-track' | 'caution' | 'behind' | 'neutral';
}

Data Source

Uses get_balance_sheet_data RPC function:

• Current Period: Balance sheet as of the end date of selected time period
• Previous Period: Balance sheet as of same date one year ago
• Cash Accounts: Filters for asset accounts with classification 'cash', 'bank', or account codes 1000-1099

Integration

Time Period Selector

The component respects the global timePeriod from the Zustand store, same as other dashboard metrics.

Entity Selector

Filters by selected entity (fund) or shows aggregate for parent org view.

Dashboard Registration

Store Types (src/store/types.ts)

// Add to DashboardComponent type
export type DashboardComponent = 
  | 'donations-chart' 
  | 'recent-donations' 
  | 'to-do-list' 
  | 'top-donors'
  | 'fund-summary';  // NEW

// Add to ADDABLE_DASHBOARD_COMPONENTS
export const ADDABLE_DASHBOARD_COMPONENTS: DashboardComponent[] = [
  'top-donors',
  'fund-summary',  // NEW
];

// Add to DASHBOARD_COMPONENT_INFO
export const DASHBOARD_COMPONENT_INFO: Record<DashboardComponent, { label: string; description: string }> = {
  // ... existing entries
  'fund-summary': { 
    label: 'Fund Summary', 
    description: 'Current fund balance with YoY comparison and health indicator' 
  },
};

App.tsx Render Switch

case 'fund-summary':
  return <FundSummaryCard />;

Implementation Files

| File | Purpose |

|------|---------|

| `src/features/dashboard/components/FundSummaryCard.tsx` | UI component |

| `src/lib/db.ts` | Add `fetchFundSummaryData()` function |

| `src/hooks/useDashboardMetrics.ts` | Add `useFundSummary()` hook |

| `src/store/types.ts` | Register component type |

| `src/App.tsx` | Add render case |

UI Mockup

┌─────────────────────────────────────┐
│  Cash Balance                    🟢 │
│  $45,230.00                         │
│  As of Jan 29, 2026                 │
│  ↗ 12.5% vs same date last year    │
│                                     │
│  View Balance Sheet →               │
└─────────────────────────────────────┘

Related Documentation

• Dashboard Overview
• Balance Sheet Report
• MetricsCard Component

Synced from IFMmvp-Frontend documentation: pages/dashboard/FUND-SUMMARY-CARD.md