Documentation — Bufdir Export UI Components
epic-bufdir-reporting-export-ui-task-014 — Write developer documentation for all five export UI components covering: component responsibilities, BLoC/Riverpod integration contract, required props and callbacks, accessibility requirements per component, design token usage, and known edge cases (expired URLs, zero-record periods, network errors). Include code examples for integrating BufdirExportTriggerScreen into a new host route.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 8 - 48 tasks
Can start after Tier 7 completes
Implementation Notes
Write documentation as Markdown files co-located with the component source or in a `/docs/bufdir-export/` folder. Use a consistent template per component: Overview → Constructor API table → BLoC/Riverpod contract → Accessibility → Design tokens → Edge cases. For the integration example, show the minimum viable GoRouter route registration, the BlocProvider tree, and how to pass the organization ID. Avoid duplicating implementation details already visible in the source — focus on the 'why' and 'how to use', not 'what the code does line by line'.
Reference the WCAG 2.2 AA standard when documenting accessibility requirements.
Testing Requirements
No automated tests required for documentation itself. Validate correctness by having one developer follow the integration example cold and confirm they can add the screen to a new route without errors. Confirm all code snippets compile by copying them into a scratch Dart file and running `dart analyze`.
For large exports that run for 10–30 seconds, a static loading spinner will feel broken to users on slow mobile connections. If the UI cannot display meaningful progress during the export pipeline, coordinators may abandon the flow or trigger duplicate exports by pressing the button multiple times.
Mitigation & Contingency
Mitigation: Implement streaming progress events from the orchestrator BLoC through named pipeline stages (querying, mapping, generating, uploading). Display each stage label with a progress indicator on the trigger screen. Disable the generate button immediately on first tap to prevent duplicates.
Contingency: If streaming pipeline progress is not feasible in the first release, implement a deterministic stage-based progress animation (10% querying, 50% generating, 90% uploading) that gives users feedback without requiring real server events.
Custom date range pickers are among the most common accessibility failures in mobile apps. Blindeforbundet users rely on VoiceOver, and NHF users include people with cognitive impairments. A non-accessible period picker could make the entire export workflow unusable for a significant portion of the intended user base.
Mitigation & Contingency
Mitigation: Build the period picker using Flutter's native date picker semantics as the foundation, with preset shortcuts as primary navigation (reducing the need to interact with the custom range picker at all). Test with VoiceOver on iOS and TalkBack on Android before UI epic sign-off. Engage Blindeforbundet's test contact for accessibility validation.
Contingency: If the custom date range picker cannot be made fully accessible before release, ship only the preset period shortcuts (covering the majority of use cases) and add the custom range picker in a follow-up sprint after dedicated accessibility remediation.