Build PeerMentorStatsListRow widget

epic-activity-statistics-dashboard-user-interface-task-007 — Implement a single PeerMentorStatsListRow widget displaying a peer mentor's name, multi-chapter label (e.g., 'Chapter A, Chapter B'), session count, and hours for the selected time window. The row must have a minimum 44dp height, include a trailing chevron icon indicating drill-down navigation, and carry full Semantics labels combining all visible fields into a single accessible description.

high priority low complexity frontend pending frontend specialist Tier 1

Acceptance Criteria

Widget renders peer mentor name as primary text using design token typography (body/title scale)

Multi-chapter label renders as comma-separated chapter names on a secondary text line; single-chapter shows that chapter name without comma

Session count and hours display in a trailing info group before the chevron icon

Row minimum height is exactly 44 logical pixels (constraints enforced via ConstrainedBox or BoxConstraints.tightFor)

Trailing Icons.chevron_right (or equivalent design token icon) is present and uses a muted/tertiary colour token

Semantics widget wraps the entire row with a combined label: '{name}, {chapters}, {sessionCount} sessions, {hours} hours, navigate to details'

excludeSemantics: true applied to all child Semantics nodes inside the row so screen readers announce only the combined label

Widget is stateless and accepts a typed PeerMentorStatsSummary data model (no raw primitives)

Renders correctly in both light and dark theme using design tokens — no hardcoded colours

Long peer mentor names truncate with ellipsis and do not overflow

Long chapter lists truncate with ellipsis and do not wrap to a third line

Widget passes flutter_test golden test against reference snapshot

Technical Requirements

frameworks

Flutter

Riverpod

data models

PeerMentorStatsSummary

performance requirements

Widget build must complete in under 16ms (one frame budget)

No expensive computations inside build(); chapter string joining done outside or cached

security requirements

No PII logged or printed from widget layer

Data passed via typed model; no raw maps accepted

ui components

ListTile or custom Row with ConstrainedBox

Design token Text styles (labelLarge, bodyMedium)

Design token colour tokens (textPrimary, textSecondary, textTertiary, iconMuted)

Semantics wrapper with combined label

Icon — chevron_right or design system equivalent

Execution Context

Execution Tier

Tier 1

Tier 1 - 540 tasks

Can start after Tier 0 completes

View Full Execution Plan

Implementation Notes

Define a PeerMentorStatsSummary data class (freezed or plain Dart) with fields: userId, displayName, chapterNames (List), sessionCount (int), totalHours (double). Compute chapterLabel = chapterNames.join(', ') outside of the build tree (in the model or a helper). Use a single Semantics node at the root with the combined string — do NOT nest multiple Semantics nodes or screen readers will announce each field individually, which violates WCAG 2.2 AA. Prefer ListTile.buildTextScaleFactor-aware sizing; if custom Row is used, wrap with ConstrainedBox(constraints: BoxConstraints(minHeight: 44)).

All colours and text styles must come from the app's DesignTokens extension on ThemeData — no Color(0x...) literals.

Testing Requirements

Unit/widget tests using flutter_test. Test cases: (1) renders all fields from a populated PeerMentorStatsSummary; (2) single-chapter label shows no trailing comma; (3) multi-chapter label joins correctly with ', '; (4) row height is >= 44px via tester.getSize(); (5) Semantics tree contains the expected combined label string — use tester.getSemantics(); (6) overflow test with 80-char name; (7) golden snapshot test. No integration tests required for this widget alone.

Component

Peer Mentor Stats List

ui medium

Dependencies (1)

Create the TimeWindow enum (week, month, quarter, year, custom) and associated value types used across all stats UI components. Define the Dart freezed data classes for StatsTimeRange and TimeWindowSelection that will be emitted by the selector and consumed by the notifier. epic-activity-statistics-dashboard-user-interface-task-001

Epic Risks (4)

high impact high prob technical

fl_chart renders chart elements on a Canvas, making individual bars and data points invisible to the Flutter Semantics tree by default. Without explicit Semantics wrappers, VoiceOver and TalkBack users receive no chart information, violating the WCAG 2.2 AA requirement mandated by all three partner organizations.

Mitigation & Contingency

Mitigation: Wrap the fl_chart widget in a Semantics node with a dynamically generated textual description of the chart data (e.g., 'Bar chart: January 12, February 8, March 15 sessions'). Implement a collapsible data table alternative beneath the chart that screen readers can navigate row by row. Validate with VoiceOver on iOS and TalkBack on Android before the epic is marked complete.

Contingency: If fl_chart's Canvas rendering cannot be made accessible within the epic timeline, ship the chart hidden from the Semantics tree with ExcludeSemantics and promote the data table alternative to first-class UI so screen reader users have full access to the information. Log a tech-debt item to revisit native chart accessibility in a future sprint.

medium impact medium prob scope

Coordinators managing up to 5 chapters (NHF requirement) require the PeerMentorStatsList to display chapter affiliation labels for each row. With large chapter lists and many peer mentors, the list could become overwhelming and cause layout overflow or scrolling performance issues on lower-end Android devices.

Mitigation & Contingency

Mitigation: Implement chapter filtering as a segmented control above the list so coordinators can scope the list to one chapter at a time. Use ListView.builder (lazy rendering) rather than a Column of all rows. Profile scroll performance on a low-end Android device (Pixel 4a equivalent) with 50 peer mentors in scope during development.

Contingency: If multi-chapter display causes unacceptable performance, ship with single-chapter scope as the default view and a chapter switcher dropdown, deferring the combined cross-chapter list to a follow-up sprint.

low impact low prob technical

Summary cards and the chart widget rebuilding simultaneously on provider state change could cause a visible jank frame on slower devices, degrading perceived quality especially since this screen is intended to feel motivating and polished for gamification purposes.

Mitigation & Contingency

Mitigation: Use AnimatedSwitcher with a short fade transition (150ms) on the stats cards and chart so that data replacement feels intentional rather than jarring. Profile with Flutter DevTools on a mid-range device and ensure no frame exceeds 16ms during a time-window switch.

Contingency: If animation introduces complexity that delays delivery, ship without animation and use a loading skeleton (shimmer effect) during re-fetch instead, which is simpler and equally effective at masking the data swap.

high impact low prob security

If the role-based screen dispatch is misconfigured, a peer mentor could navigate to the coordinator stats screen and see aggregated chapter data for all peer mentors, which is a data privacy violation and a compliance risk for all three organizations.

Mitigation & Contingency

Mitigation: Implement role guard at the router level using an existing role-route-guard component so the coordinator screen route is unreachable for peer mentor roles. Add a widget test that mounts the coordinator screen with a peer mentor session token and asserts that the guard redirects to the no-access screen.

Contingency: If a bypass is found in QA, add a secondary in-screen role assertion in the coordinator screen's initState that throws an AuthorizationException and navigates to the error screen, ensuring defence in depth regardless of router configuration.

Quick Links

All Tasks Execution Plan