Implement PauseConfirmationDialog widget
epic-peer-mentor-pause-ui-state-task-001 — Build the PauseConfirmationDialog modal widget that explains pause consequences to the peer mentor, collects an optional free-text reason, and emits either a confirmed or cancelled outcome via callbacks. The dialog must use accessible semantics, trap focus within the modal, and meet WCAG 2.2 AA contrast and touch-target requirements.
Acceptance Criteria
Technical Requirements
Implementation Notes
Place the widget at lib/features/peer_mentor/widgets/pause_confirmation_dialog.dart. Use a showPauseConfirmationDialog(BuildContext context) helper function that calls showDialog() with barrierDismissible: false — this keeps the caller code clean. Internally, use a StatefulWidget with a TextEditingController for the reason field, disposed in dispose(). Reuse existing AppButton and AppTextField widgets to maintain visual consistency and reduce test surface.
For the back button, wrap the Dialog content in WillPopScope (or PopScope on Flutter 3.16+) that calls onCancelled and returns false to prevent automatic pop. Do not put any BLoC or Riverpod calls inside this widget — it must be pure UI with callbacks, making it easily testable and reusable across coordinator and mentor contexts.
Testing Requirements
Write widget tests covering: (1) dialog renders title, body text, and reason field; (2) confirm button triggers onConfirmed with null when reason field is empty; (3) confirm button triggers onConfirmed with typed text when reason field has content; (4) cancel button triggers onCancelled; (5) dialog cannot be dismissed by tapping the barrier; (6) device back button triggers onCancelled. Also write a contrast check test using flutter_test's AccessibilityGuidelines: tester.ensureSemantics() + expectLater(tester, meetsGuideline(textContrastGuideline)). No integration tests required for this widget alone.
PauseConfirmationDialog must meet WCAG 2.2 AA focus trap requirements: when the dialog opens, focus must move to the first interactive element; when it closes, focus must return to the triggering toggle. Flutter's default showDialog does not always guarantee correct focus restoration on Android, which could trap screen-reader users.
Mitigation & Contingency
Mitigation: Use a custom modal implementation wrapping Flutter's Dialog with explicit FocusScope management and test with TalkBack on Android and VoiceOver on iOS during development, not just in final QA. Reference the accessible-modal-sheet pattern already used elsewhere in the codebase.
Contingency: If full WCAG focus management cannot be achieved within the sprint, ship the feature with a documented accessibility defect and schedule a dedicated accessibility remediation task. Communicate the known gap to the accessibility stakeholder at HLF/NHF.
If the user taps the PauseReactivateToggle rapidly before the BLoC emits a loading state, multiple PauseMentorEvents could be added to the BLoC stream, resulting in duplicate service calls and inconsistent UI state (toggle flickering between states).
Mitigation & Contingency
Mitigation: Disable the toggle widget immediately on first tap by emitting MentorStatusLoading synchronously before the async service call begins. Use BLoC's event transformer with droppable() to discard subsequent events while a transition is in progress.
Contingency: If BLoC event deduplication is not sufficient, add a debounce at the widget level (300 ms) and a server-side idempotency check in MentorStatusService that no-ops if the requested transition is already in progress.
PauseStatusBanner must conditionally render the reactivate shortcut only for users with coordinator permission. If the permission check relies on a stale role state in the Riverpod provider, a peer mentor could briefly see a reactivate action they are not authorised to use, which could cause a confusing permission-denied error if tapped.
Mitigation & Contingency
Mitigation: Source the permission check directly from the role-resolution Riverpod provider (which is kept in sync with Supabase auth) rather than from local component state. Add a widget test asserting the shortcut is absent when the user role is peer_mentor.
Contingency: If the shortcut is accidentally shown to an unauthorised user, the underlying MentorStatusService enforces role validation server-side, so the worst outcome is a visible error message rather than an actual unauthorised state change.