Reports Hub

Reports Hub

Component File: src/features/reports/components/ReportsHub.tsx Route / navigation: Base path `/reports` (PageView reports). Tool selection: Zustand `reportTool` (ReportTool in src/store/types.ts), mirrored to `/reports/{reportTool}` (and `/reports/{reportTool}/{recordId}` for deep links). Last Updated: April 13, 2026 Status: Current

Overview

The Reports hub exposes the finance and donor reporting tools currently wired into PageRouter.tsx.

Hub consolidation

The Reports hub uses the Phase 1 hub consolidation pattern documented in `../../plans/HUB-CONSOLIDATION.md`. Report tiles remain the same routed tools, but the hub groups them into expanded full-width sections and supports cross-device favorites saved in user_preferences.ui_preferences.reportHubFavorites.

Favorite stars are passed through HubItem.action. The shared HubGrid renders tile-mode actions in the card header so report titles and descriptions keep their own space on mobile, while the favorite button keeps the required 44px mobile touch target.

Table pagination

Report tools that show large row lists use the app-wide table pattern documented in documentation/frontend/STYLING-GUIDE.md (`PaginationControls`, row-size `Select`). Most client-paged tables use 100 / 250 / 500 rows; Transaction Ledger, Donation Settlement Report, and Event Financial Summary (registration table) use 25 / 50 / 100 and place `PaginationControls` above and below the table. Donor Reporting, Lapsed Donor, Donation Settlement Report, and Transaction Ledger fetch user-facing pages from the server. Revenue Reconciliation now fetches complete in-range data using internal 5,000-row server chunks (to avoid hard-cap truncation), then paginates donor rows on the client. Household Giving, A/P & A/R Aging (including vendor bills drill-down), Volunteer Hours (main table + sheet), the Mileage fund drawer, and Event Financial Summary (after loading registrations for the selected event) paginate on the client after load so the DOM stays small.

Current reportTool ids (match ReportTool type)

• balance-sheet
• income-statement
• transaction-ledger
• balance-sheet-by-fund
• income-statement-by-fund
• aging-report
• comparative-report
• fund-analytics
• cash-flow-statement
• donor-reporting
• donation-settlement-report
• daf-contributions-report
• mileage-report
• volunteer-hours-report
• household-giving-report
• lapsed-donor-report
• bank-reconciliation-reports
• event-financial-report

Notes

• Date nudge shortcut (Apr 2026): On the Reports page, shared DatePicker controls support QuickBooks-style day nudging. Focus a valid report date field and press `+` to move forward one day or `-` to move backward one day. Manual typing still works; the shortcut only intercepts valid dates.
• Drill-down drawer dates (April 2026): On reports that sync a ledger drawer date range with the main report (Balance Sheet, Balance Sheet by Fund, Income Statement, Income Statement by Fund, Cash Flow, Revenue Reconciliation), the UI does not overwrite in-drawer date edits while the drawer is open. When the drawer is closed, drawer dates stay aligned with the report so the next open matches. Opening a new line or cell resets the drawer to the current report range (Balance Sheet by Fund: fiscal-year start through as-of, with calendar-year start of as-of as fallback when fiscal metadata is not on the payload yet). See per-report docs for detail.
• Financial statements (balance sheet, income statement, cash flow, by-fund variants, comparative) display the organization’s accounting basis from Chart of Accounts → Account Defaults on the report header and on PDF exports where applicable.
• Income statement parity (standard + by-fund + revenue reconciliation GL baseline): see `../../contracts/INCOME-STATEMENT-PARITY.md`.
• Balance sheet parity (consolidated + by-fund + RPC lock / Steve sign-off for DB changes): see `../../contracts/BALANCE-SHEET-PARITY.md` and `../../contracts/BALANCE-SHEET-INVARIANTS.md`.
• route ids like ap-aging, comparative, or household-giving are stale aliases from older docs, not the current router ids
• bank-reconciliation-reports is a live report and now has its own doc
• balance-sheet-by-fund and household-giving-report are live reports and now have explicit page docs here as well

Parent-org restricted reports (Mar-Apr 2026)

These tools are hidden from fund users (fund_user role). Parent-org admins can access them based on per-tool tier gates, and internal support users follow the same role/tier visibility rules for these tiles.

| `reportTool` | Access | Rationale |

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

| `balance-sheet-by-fund` | Parent org + Pro/Enterprise | Multi-fund column layout is an org-wide view. |

| `income-statement-by-fund` | Parent org + Pro/Enterprise | Same. |

| `donation-settlement-report` | Parent org (all paid tiers) | Donor contact + Stripe payout detail is an org-wide finance export. |

| `bank-reconciliation-reports` | Parent org (all paid tiers) | Saved reconciliation snapshots across accounts; parent-org scope. |

Implementation: ReportsHub sets parentOrgProEnterpriseOnly: true for by-fund statement tiles and parentOrgOnly: true for Donation Settlement Report and Bank Reconciliation Reports. HubGrid enforces both role and tier visibility, while PageRouter applies matching guards (ReportParentOrgOnlyDenied with reason="parentOrg" or reason="proTier"). Global search mirrors this with searchIndex.parentOrgOnly / searchIndex.parentOrgProEnterpriseOnly and searchEngine.hasAccess.

Related Docs

• documentation/pages/reports/01-BALANCE-SHEET-REPORT.md
• documentation/pages/reports/02-INCOME-STATEMENT-REPORT.md
• documentation/pages/reports/03-CASH-FLOW-REPORT.md
• documentation/pages/reports/05-VOLUNTEER-HOURS-REPORT.md
• documentation/pages/reports/07-DONOR-REPORTING.md
• documentation/pages/reports/19-DONATION-SETTLEMENT-REPORT.md
• documentation/pages/reports/08-COMPARATIVE-REPORT.md
• documentation/pages/reports/09-MILEAGE-REPORT.md
• documentation/pages/reports/10-FUND-ANALYTICS.md
• documentation/pages/reports/11-AGING-REPORT.md
• documentation/pages/reports/12-INCOME-STATEMENT-BY-FUND.md
• documentation/pages/reports/13-LAPSED-DONOR-REPORT.md
• documentation/pages/reports/14-BALANCE-SHEET-BY-FUND.md
• documentation/pages/reports/15-HOUSEHOLD-GIVING-REPORT.md
• documentation/pages/reports/16-BANK-RECONCILIATION-REPORTS.md
• documentation/pages/reports/17-TRANSACTION-LEDGER-REPORT.md
• documentation/pages/reports/18-EVENT-FINANCIAL-REPORT.md

Report documentation tiers (April 2026 audit)

Use this to choose the right contract doc when changing reports:

| Tier | Reports | Contract / notes |

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

| **A — Locked financial statements** | Balance Sheet, Balance Sheet by Fund, Income Statement, Income Statement by Fund | [`BALANCE-SHEET-PARITY.md`](../../contracts/BALANCE-SHEET-PARITY.md), [`BALANCE-SHEET-INVARIANTS.md`](../../contracts/BALANCE-SHEET-INVARIANTS.md), [`INCOME-STATEMENT-PARITY.md`](../../contracts/INCOME-STATEMENT-PARITY.md); BS RPC edits need triple confirmation + Steve sign-off. |

| **B — Same RPCs as statement tools** | Cash Flow, Comparative (IS/BS/CF modes), Revenue Reconciliation (accounting) | [`INCOME-STATEMENT-PARITY.md`](../../contracts/INCOME-STATEMENT-PARITY.md) for P&L; Comparative BS mode also [`BALANCE-SHEET-PARITY.md`](../../contracts/BALANCE-SHEET-PARITY.md). |

| **C — Analytics / hybrid / operational** | Fund Analytics, Transaction Ledger, Event Financial, Aging, Donor / Household / Lapsed / Volunteer / Mileage, Bank Reconciliation Reports | Not guaranteed to match Tier A totals; see per-page doc (`10-FUND-ANALYTICS.md`, `17-TRANSACTION-LEDGER-REPORT.md`, etc.) and [`FINANCIAL-REPORT-CONTRACT.md`](../../contracts/FINANCIAL-REPORT-CONTRACT.md) for shared ledger semantics where applicable. |

Synced from IFMmvp-Frontend documentation: pages/reports/00-REPORTS-HUB.md