Integrate map provider into map view screen canvas
epic-geographic-peer-mentor-map-ui-accessibility-task-005 — Integrate the map provider plugin (flutter_map or google_maps_flutter) into MapViewScreen to render the full-screen tile layer. Configure initial camera position, zoom constraints, and gesture handling. Ensure the map canvas has a Semantics excludeSemantics wrapper with a descriptive label so screen readers receive the list fallback instead of attempting to traverse the map. Add keyboard navigation support for zoom controls.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 2 - 518 tasks
Can start after Tier 1 completes
Implementation Notes
Prefer flutter_map over google_maps_flutter if Mapbox tile hosting is already confirmed — flutter_map is open-source and avoids Google dependency. Use flutter_map's TileLayer with a Mapbox tile URL template. Load the Mapbox public access token from a --dart-define compile-time variable (e.g., MAPBOX_PUBLIC_TOKEN) injected in CI — document this in the project README. The Semantics(excludeSemantics: true) wrapper is critical for Blindeforbundet users: the map canvas is inherently inaccessible to screen readers, so the list view must be the primary accessible path.
Do not attempt to make the map itself fully accessible — instead, ensure the list fallback (task 001) is polished and the toggle button (task 002) is prominently accessible. Use MapController.dispose() in the StatefulWidget's dispose() method to prevent memory leaks. For the tile loading indicator, show it based on a TileLayer onTileError / loading callback rather than a timer.
Testing Requirements
Unit tests: verify map controller is disposed on unmount; verify zoom clamping logic (min 4, max 17). Widget tests: verify Semantics(excludeSemantics: true) is applied to map canvas — use tester.getSemantics() and assert no child semantics nodes under the map; verify zoom buttons are reachable by keyboard traversal; verify loading indicator appears before tiles are ready; verify error banner appears on simulated tile load failure. Integration tests: verify tile loading does not make requests to any endpoint other than the configured Mapbox tile URL. Performance test: 60fps assertion during zoom gesture simulation.
Coverage target: 85%+ on MapViewScreen integration logic.
Flutter's map canvas (flutter_map) does not natively support semantic focus traversal for screen readers, meaning map markers may be entirely invisible to VoiceOver/TalkBack users. If the accessible list fallback is not treated as a first-class view, screen reader users will have no access to the feature.
Mitigation & Contingency
Mitigation: From sprint 1, treat mentor-list-fallback as a fully featured primary view, not an afterthought. Implement and test it in parallel with the map canvas. Make the view-toggle-button keyboard focusable and announced on every screen state. Conduct VoiceOver testing on device before submitting each PR touching UI components.
Contingency: If map canvas accessibility cannot be achieved for marker focus traversal, make the view-toggle-button the default focus target on screen load for VoiceOver users (detected via screen-reader-detection-service) so they are immediately directed to the list fallback without needing to discover the toggle.
The mentor-info-popup must occupy no more than 40% of visible map area on small screens. On devices with screen heights under 667px (iPhone SE), overlapping with the filter panel or obscuring most of the map could severely degrade usability.
Mitigation & Contingency
Mitigation: Implement the popup as a bottom sheet capped at 40% of screen height with a ScrollView for overflow content. Test on iPhone SE (375x667pt) and the smallest commonly used Android form factor in the device lab. Define max-height as a percentage constant in location-privacy-config or design tokens.
Contingency: If the popup cannot fit all required fields within 40% height on smallest targets, truncate assigned contact count and certification badge to icons-only in the compact view, with a 'View Profile' button always visible at the bottom of the popup regardless of scroll position.
Filter state must remain perfectly synchronised between the map view and the list fallback. If the filter panel emits state that is not consumed identically by both views, coordinators switching between views will see inconsistent mentor sets, eroding trust in the feature.
Mitigation & Contingency
Mitigation: Store active filter criteria in a single shared Riverpod provider owned by the map-view-screen and consumed by both map-marker-widget (via mentor-location-service) and mentor-list-fallback. Write integration tests that apply a filter, switch views, and assert identical mentor counts in both views.
Contingency: If filter sync proves brittle, simplify to a single filter state object passed explicitly as a constructor argument to both views on each rebuild, eliminating indirect state sharing.