Build Speech-to-Text Field Overlay Widget
epic-structured-post-session-report-form-engine-task-009 — Implement the per-field microphone trigger overlay widget. Render a microphone IconButton that transitions through idle, listening (animated waveform), processing, and error states. Display partial transcription in a floating preview card above the field. Announce recording state transitions via Flutter Semantics live regions for WCAG 2.2 AA compliance. Tap outside or press ESC to cancel recording. On final transcription, invoke onTranscribed callback to fill the parent field.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 1 - 540 tasks
Can start after Tier 0 completes
Implementation Notes
Use a StatefulWidget with TickerProviderStateMixin for the AnimationController. Subscribe to ISpeechToTextAdapter.stream in initState() and cancel in dispose() — never in build(). For the floating preview card, prefer the Flutter Overlay API (OverlayEntry inserted into Overlay.of(context)) over a Stack approach, as it naturally renders above all other widgets including the keyboard. Position the card using CompositedTransformFollower/Leader pair anchored to the mic button's RenderBox.
For the tap-outside-to-dismiss, wrap the listening state with a ModalBarrier (color: Colors.transparent) that calls _cancelRecording() on tap. The waveform animation: three AnimationControllers offset by 120ms each, driving a scale or height tween on three Container bars — extract into _WaveformAnimationWidget to keep the parent widget lean. AppLifecycleListener: pause/resume the waveform AnimationController in the lifecycle callback. For WCAG 2.2 AA: wrap state-change messages in a Semantics widget with liveRegion: true inside the overlay card — this fires on iOS VoiceOver and Android TalkBack.
Design tokens: use the project's token system for colors, spacing, and radii — no hardcoded values.
Testing Requirements
Widget tests (flutter_test): (1) idle state — mic button rendered, tappable, no overlay visible; (2) tap mic → adapter startListening called, waveform animation running, preview card visible; (3) inject PartialResult event → preview card text updated; (4) inject FinalResult event → onTranscribed called with correct text, overlay dismissed, idle state restored; (5) inject ErrorEvent → error icon shown, error message in preview card, auto-dismiss after 2 seconds (use fake async); (6) tap outside overlay during listening → stopListening called, onTranscribed NOT called; (7) ESC key press → stopListening called; (8) isEnabled=false → button non-tappable (no gesture response); (9) SttError.unavailable on init → button opacity 0.4, no tap response. Golden tests for all 4 visual states (idle, listening, processing, error) on a 390×844 canvas. Accessibility test: SemanticsController assertions for liveRegion announcements on state transitions. Use a FakeSpeechToTextAdapter (StreamController-based) as the Riverpod override in all tests.
Dynamically rendered form fields built from runtime JSON schema are significantly harder to make accessible than statically declared widgets — Flutter's Semantics tree must be correct for every possible field type and every validation state. Failures here block the entire feature for Blindeforbundet's visually impaired peer mentors.
Mitigation & Contingency
Mitigation: Define WCAG 2.2 AA semantics requirements for each field type before implementation and write widget tests using Flutter's SemanticsController for every type. Include a real-device VoiceOver test session in the acceptance gate for this epic before marking it done.
Contingency: If dynamic semantics prove too difficult to get right generically, implement field-type-specific Semantics wrappers (one per supported field type) instead of a single generic renderer, accepting slightly more code duplication in exchange for reliable accessibility.
The report-form-orchestrator must manage a complex state machine — schema loading, draft persistence, per-field validation, submission retries, and error recovery — across multiple async operations. Incorrect state transitions could result in lost user data, double submissions, or UI freezes.
Mitigation & Contingency
Mitigation: Define all Bloc states and events explicitly as sealed classes before writing any logic. Use a state machine diagram reviewed by the team before implementation. Write exhaustive Bloc unit tests covering every state transition, including concurrent events and network interruption mid-submission.
Contingency: If Bloc complexity becomes unmanageable, extract draft persistence into a separate DraftManagerCubit and keep report-form-orchestrator focused solely on the submit workflow. The additional granularity makes each component independently testable.
Organisations may require field types beyond the five currently specified (text, multiline, checkbox group, radio, date). If a new type is discovered during pilot testing, the dynamic-field-renderer must be extended, potentially requiring changes across multiple layers.
Mitigation & Contingency
Mitigation: Design dynamic-field-renderer as a registry of field-type renderers with a clear extension point. Document the pattern for adding a new field type so that it can be done in one file without touching existing renderers.
Contingency: If an unhandled field type is encountered at runtime, dynamic-field-renderer renders a labelled plain-text fallback widget and logs a warning so the missing type is surfaced in monitoring, preventing a crash while making the gap visible.