Org Hierarchy Navigator: Accessibility and Keyboard Navigation
epic-admin-portal-core-services-task-015 — Ensure OrgHierarchyNavigator fully complies with WCAG 2.2 AA. Add semantic labels to every tree node, role='treeitem' semantics, announce expand/collapse actions via live region, and support keyboard tab navigation through nodes. Validate with Flutter accessibility audit tooling.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 5 - 253 tasks
Can start after Tier 4 completes
Implementation Notes
Flutter does not have a native ARIA treeitem role, so approximate it with Semantics(role: SemanticsRole.button, label: ...). Use the 'expanded' and 'collapsed' semantic properties (Semantics.expanded) where available in the Flutter version in use — fall back to embedding the state in the label string if the property is not supported. For keyboard navigation, wrap the entire tree in a FocusScope and assign FocusNodes to each visible node in list order; use FocusScope.of(context).nextFocus() on Tab keypress captured via a RawKeyboardListener. Be careful not to assign FocusNodes to hidden (collapsed) nodes — rebuild the FocusNode list whenever expansion state changes.
Coordinate with the design system team to confirm all design-token colors pass the 4.5:1 contrast check before implementation; flag any tokens that fail and propose alternatives.
Testing Requirements
Semantics tests (flutter_test SemanticsController): (1) assert every visible node has the correct label pattern including depth and expansion state; (2) assert expand action triggers SemanticsService.announce with correct message; (3) assert search result count is announced via live region; (4) assert breadcrumb segments have button role and descriptive labels. Run Flutter's built-in accessibility audit via FlutterTest.ensureSemantics() and SemanticsController.checkSemantics(). Manual validation: test VoiceOver on iOS Simulator and TalkBack on Android Emulator, navigating through a 3-level hierarchy using only the keyboard/accessibility gestures and confirming correct announcements at each step.
OrgHierarchyNavigator rendering NHF's full 1,400-chapter tree in a single widget may cause Flutter frame-rate drops below 60 fps on mid-range devices, making the navigator unusable for NHF national admins.
Mitigation & Contingency
Mitigation: Implement lazy expansion: only load immediate children on node expand rather than the full tree upfront. Use virtual scrolling for long sibling lists. Test with a synthetic 1,400-node dataset on a low-end Android device during development.
Contingency: If lazy expansion is insufficient, replace the tree widget with a paginated drill-down navigator (select level → select child) that avoids rendering more than 50 nodes at a time.
Bufdir may update their required export column structure or file format during or after development. If the AdminExportService hardcodes the current Bufdir schema, any format change requires a code release rather than a config update.
Mitigation & Contingency
Mitigation: Drive the Bufdir column mapping from a configuration repository rather than hardcoded constants. Abstract column definitions into a named schema config so that format changes require only a config update and re-deployment without service logic changes.
Contingency: If Bufdir format changes post-launch, release a config update within one sprint. If the change is structural (new required sections), scope a targeted service update and communicate timeline to partner organisations.
Role transition side-effects in UserManagementService (e.g., certification expiry removing mentor from chapter listing, pause triggering coordinator notification) may interact with external services like HLF's website sync. Incomplete side-effect handling could leave the system in an inconsistent state.
Mitigation & Contingency
Mitigation: Model side-effects as explicit domain events published after the primary state change is persisted. Implement event handlers as idempotent operations so re-processing is safe. Write integration tests that assert all side-effects fire correctly for each role transition type.
Contingency: If a side-effect fails after the primary change is persisted, log the failure with full context and trigger a manual reconciliation alert to the on-call team. Provide an admin-accessible re-trigger action for failed side-effects.
If AdminStatisticsService cache TTL is set too long, org_admin may see significantly stale KPI values (e.g., a mentor newly paused an hour ago still appears as active), undermining trust in the dashboard.
Mitigation & Contingency
Mitigation: Default cache TTL to 5 minutes with a manual refresh action on the dashboard. Implement cache invalidation triggered by UserManagementService write operations that affect counted entities.
Contingency: If staleness causes org admin complaints post-launch, reduce TTL to 60 seconds and introduce a real-time Supabase subscription for high-impact counters (paused mentors, expiring certifications).