Stats Summary Cards
Component Detail
Description
A row of stat cards displaying the key KPIs: total sessions, total hours, and (for peer mentors) pending reimbursement amount. Uses the design token system for consistent styling. Cards are read-only and update reactively when the underlying Riverpod provider emits new data.
stats-summary-cards
Summaries
The Stats Summary Cards component delivers immediate visibility into the program's most critical performance indicators — total sessions held, hours contributed, and outstanding reimbursement balances — directly on the peer mentor's mobile dashboard. By surfacing these KPIs at a glance, the organization reduces administrative overhead associated with manual reporting, empowers peer mentors to self-track their contributions, and ensures reimbursement obligations are never overlooked. This transparency directly supports volunteer retention by giving mentors confidence that their time and expenses are accurately recorded, reducing disputes and building trust in the program's financial accountability processes.
Stats Summary Cards is a low-complexity UI component with no external service dependencies, making it one of the lowest-risk deliverables in the mobile feature set. Development effort is minimal — the component consumes a pre-composed StatsSnapshot object, so its delivery is gated on the upstream data provider being finalized rather than any internal complexity. Key scheduling consideration: the reimbursement card is conditionally rendered for peer mentor role only, so role-based rendering logic must be tested across both user types. QA should verify null/zero state rendering and reactive updates when the Riverpod provider emits new data.
No backend integration work is required for this component itself.
StatsSummaryCards is a stateless Flutter widget consuming a StatsSnapshot value object passed from the parent screen, which sources it via a Riverpod provider watch. The component exposes three builder methods — buildSessionCard, buildHoursCard, and buildReimbursementCard — each returning a styled card widget using the project's design token system (colors, typography, spacing). The reimbursementCard accepts a nullable double; when null, it renders a role-appropriate empty label rather than a zero value. Reactivity is inherited from the parent's ConsumerWidget rebuild cycle — this component itself holds no state.
Ensure token references are imported from the shared theme barrel file, not hardcoded, to remain consistent with future theme updates.
Responsibilities
- Display session count, hours contributed, and reimbursement totals
- Apply design token colors and typography consistently
- Update reactively on provider state changes
- Handle null/zero states gracefully with appropriate labels
Interfaces
StatsSummaryCards({required StatsSnapshot snapshot})
buildSessionCard(int count)
buildHoursCard(double hours)
buildReimbursementCard(double? amount)
Relationships
Dependents (2)
Components that depend on this component