Proxy Mode Selector audit trail explanation UI
epic-bulk-and-proxy-registration-mentor-selection-task-002 — Add the inline audit trail explanation copy to the Proxy Mode Selector Screen, clearly communicating to coordinators that proxy-created records are attributed to the peer mentor, not to themselves. Render the explanation as accessible body text beneath each mode card using plain language content aligned with cognitive accessibility requirements.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Pass the explanation text as an optional `explanationText` parameter to `ProxyModeOptionCard` (created in task-001). Render it as a `Text` widget inside a `Padding` below the card's title/icon area. Use `Semantics(container: false)` so the text flows naturally into the card's semantic node rather than creating a separate focus stop — this gives a better screen reader experience where the mode name and its explanation are announced together. Store both explanation strings in the app's ARB localisation file (or equivalent) under keys like `proxyMode_single_explanation` and `proxyMode_group_explanation`.
Keep each string under 100 characters to avoid excessive wrapping on small screens. The cognitive accessibility principle from the workshop notes ('lowest possible cognitive load') should guide the copy: prefer 'This records activities for the peer mentor, not you' over longer explanations.
Testing Requirements
Manual accessibility verification: (1) enable VoiceOver on iOS and navigate to the screen — confirm explanation text is announced after the card title in correct order, (2) use the Flutter accessibility inspector to confirm contrast ratio passes 4.5:1, (3) test text wrapping at 320px width. No automated widget test required for this copy-only task, but confirm the existing widget test suite (if any) still passes after the change.
NHF coordinators may manage dozens of peer mentors across multiple chapters. If the multi-select list renders all contacts in a single unsorted ListView, performance degrades with 50+ items, and coordinators cannot efficiently locate a specific mentor, increasing the probability of selection errors and wrong-person proxy registrations.
Mitigation & Contingency
Mitigation: Use a SliverList with itemExtent for fixed-height rows to enable O(1) scroll position calculation. Implement the search filter using a debounce utility operating on an in-memory list (no extra API calls). Sort the contact list alphabetically by default. Add chapter-filter chips above the list for NHF's multi-chapter coordinators.
Contingency: If performance issues arise in testing with real data sets, introduce pagination with a 'load more' trigger at the bottom of the list and cache rendered rows using Flutter's AutomaticKeepAliveClientMixin.
NHF has a complex 12-national-association / 9-region / 1,400-chapter hierarchy. It is ambiguous whether a coordinator can proxy-register for peer mentors outside their immediately assigned chapter. If the contact list is not correctly scoped by RLS, coordinators might see — and register on behalf of — peer mentors they do not manage, creating fraudulent activity records that skew Bufdir statistics.
Mitigation & Contingency
Mitigation: The Proxy Contact List Provider must query only peer mentors linked to the coordinator's own chapter scope via RLS. Add an explicit Supabase query test asserting that a coordinator from chapter A cannot retrieve peer mentors from chapter B. Display each mentor's chapter affiliation in the list row so coordinators can visually verify scope.
Contingency: If RLS scope is found to be too permissive in testing, apply a server-side coordinator_id filter as a secondary guard on the query. Block the feature release until the scope test passes consistently.