Donor Reporting

Donor Reporting

Component File: src/features/reports/components/DonorReporting.tsx Route / navigation: Path /reports, Zustand reportTool = donor-reporting. See 00-REPORTS-HUB.md. Access Level: Parent Org and Fund Users with Reports access (position-based)

Overview

Donor Reporting generates and sends end-of-year tax reports to donors. It provides a comprehensive interface for selecting donors, previewing tax receipts, and batch-sending annual giving statements for tax purposes.

UI Features

Main Features

• Header:
• Title: "Donor Reporting"
• Subtitle: "Generate and send end-of-year tax reports to donors"
• Back to Reports Hub button

Stats Cards (4 cards)

1. Total Donors - Count of donors with YTD donations 2. Selected - Count of currently selected donors 3. [Year] Total - Sum of all YTD donations 4. Report Year - Currently selected tax year

Search and Filters

• Search by donor name or email
• Year selector dropdown
• Select All / Deselect All functionality

Action Buttons

• Send Reports - Batch send to selected donors (email)
• Snail mail - Opens Fundraising → Snail Mail with mailable selected donors pre-selected
• Export (toolbar) - Opens export dialog: donor list as CSV, XLSX, or PDF

Donors Table

Columns:

• Checkbox for selection
• Donor Name (with avatar initials)
• Email (or “No Email” badge)
• Mail — mailable address status (OK vs incomplete address)
• Fund (entity they donated to)
• [Year] Total — donations for the selected report year
• Donations — count of gifts in that year
• Actions — row kebab menu (three dots, same pattern as other managers):
• View report — opens the tax receipt preview dialog for that donor
• Download PDF — downloads a single-donor tax receipt PDF (landscape, via exportToPDF: donor info, contribution lines, total, tax statement; parent org letterhead fields when available)

Preview Report Dialog

Shows a preview of the tax receipt including:

• Organization letterhead
• Donor information
• Donation summary by date
• Total contributions
• Tax-deductible statement
• IRS compliance language

Send Confirmation Dialog

Confirms batch sending of reports to selected donors.

Data Requirements

DonorWithYearDonations (table row)

Loaded from fetchDonorsForReporting in lib/db/donors.ts — includes donations[] for the report year, ytdTotal, donationCount, hasMailableAddress, entityId, etc.

Stats Object

interface Stats {
  totalDonors: number;
  selectedCount: number;
  totalYTD: number;
  selectedYTD: number;
}

State Management

Local State

• searchQuery / debouncedSearch — search filter
• selectedDonorIds — Set of selected donor IDs
• previewDialogOpen — preview dialog visibility
• sendConfirmOpen — send confirmation dialog visibility
• previewDonor — donor being previewed (DonorWithYearDonations | null)
• exportDialogOpen — data export dialog visibility
• reportYear, pageSize, currentPage — report scope and pagination
• downloadingPdfDonorId — disables per-row PDF download while generating

Global State (Zustand Store)

• setReportTool - Navigation function (from useAppStore)

Key Functions

Selection

• handleSelectAll() - Toggle select/deselect all visible donors
• handleSelectDonor(donorId) - Toggle individual donor selection

Actions

• handlePreviewReport(donor) — open preview dialog for donor
• handleDownloadDonorReportPdf(donor) — build and download one donor’s tax receipt PDF
• handleSendReports() / confirmSendReports() — batch email send via sendTaxReports
• handleOpenSnailMailForSelection() — stash intent in sessionStorage and navigate to Snail Mail
• handleExport(options) — bulk export donor list (CSV / XLSX / PDF) via DataExportDialog

Filtering

• Filters donors by search query
• Filters to only show donors with YTD donations > 0
• Sorts alphabetically by name

Dependencies

Internal Dependencies

• useAppStore - Zustand global state
• fetchDonorsForReporting - Donor data with donations from Supabase
• UI components (Card, Button, Badge, Checkbox, Table, Dialog, Select, Input, DropdownMenu)
• PageHeader, Breadcrumb, PaginationControls, DataExportDialog
• exportToPDF / exportToCSV / exportToExcel from lib/exportUtils
• React Query — fetchDonorsForReporting, fetchParentOrgInfo

External Libraries

• lucide-react — Search, Send, Eye, Download, FileText, Printer, MoreVertical, etc.
• sonner — Toast notifications
• @tanstack/react-query — Donor list fetching

Use Cases

1. Year-End Tax Receipts - Generate annual giving statements 2. Batch Email - Send reports to multiple donors at once 3. Preview Before Send - Review individual reports before sending 4. Donor Selection - Choose specific donors or select all 5. Multi-Year Support - Generate reports for previous years 6. Export for Records - Download full donor list (CSV / XLSX / PDF) from the toolbar 7. Per-donor PDF - Download one tax receipt PDF from the row actions menu

Tax Receipt Content

The generated report includes:

• Organization name and address
• Donor name and address
• Tax year
• Itemized list of donations with dates and amounts
• Total contributions
• Statement that no goods/services were provided
• IRS compliance statement
• Organization EIN

Related Documentation

• 00-REPORTS-HUB.md
• ../donors/01-DONORS-CRM.md
• ../donors/02-DONATIONS-MANAGER.md

Synced from IFMmvp-Frontend documentation: pages/reports/07-DONOR-REPORTING.md