Implement TranscriptionPreviewField core widget
epic-speech-to-text-input-user-interface-task-006 — Create the TranscriptionPreviewField Flutter widget that wraps a standard TextField and displays live partial transcription results in a visually distinct preview area below the cursor. The widget must observe TranscriptionStateManager for partial results and update the preview text in real time. Support all standard OS text editing gestures (tap, long-press, drag-to-select) on the underlying field.
Acceptance Criteria
Technical Requirements
Implementation Notes
Structure the widget as a ConsumerStatefulWidget to manage the optional internal TextEditingController lifecycle. Use a Column with the TextField on top and an AnimatedSize-wrapped Container below for the preview area — AnimatedSize prevents sudden layout shifts when the preview appears. Watch TranscriptionStateManager with ref.watch and extract partial text via a pattern-match on the state type. Use a Text widget with italic TextStyle using design token colors for the preview.
Do NOT insert partial text into the TextEditingController — it must remain in a separate preview widget; merging happens only in task-007. Apply `Semantics(liveRegion: true, label: 'Speech preview', child: previewText)` to the preview widget. Expose standard TextField parameters (controller, decoration, keyboardType, textInputAction, onSubmitted) as pass-through constructor params to keep the widget flexible for reuse across multiple form fields.
Testing Requirements
Widget tests: Render TranscriptionPreviewField in isolation with a mocked TranscriptionStateManager. Assert preview area is absent when state is idle. Drive partial results into the provider and assert preview text matches. Assert TextField is focusable and receives text input normally.
Assert custom TextEditingController is not disposed if passed by caller. Golden tests: Capture widget snapshot in idle state, recording+partial state, and processing state for visual regression. Unit tests: Test the partial-result-to-preview-text mapping logic. Manual tests: Run on device, start dictation, verify preview updates in real time.
Verify all standard gestures (tap, double-tap, long-press, drag-select) function on the TextField while preview is active. Run with VoiceOver/TalkBack and confirm preview area announces updates.
Merging dictated text at the current cursor position in a TextField that already contains user-typed content is non-trivial in Flutter — TextEditingController cursor offsets can behave unexpectedly with IME composition, emoji, or RTL characters, potentially corrupting the user's existing notes.
Mitigation & Contingency
Mitigation: Implement the merge logic using TextEditingController.value replacement with explicit selection range calculation rather than direct text manipulation. Write targeted widget tests covering edge cases: cursor at start, cursor at end, cursor mid-word, existing content with emoji, and content that was modified during an active partial-results stream.
Contingency: If cursor-position merging proves too fragile for the initial release, scope the merge behaviour to always append dictated text at the end of the existing field content and add the cursor-position insertion as a follow-on task after the feature is in TestFlight with real user feedback.
VoiceOver on iOS and TalkBack on Android handle rapid sequential live region announcements differently. If recording start, partial-result, and recording-stop announcements arrive within a short window, they may queue, overlap, or be dropped, leaving screen reader users without critical state information.
Mitigation & Contingency
Mitigation: Implement announcement queuing in AccessibilityLiveRegionAnnouncer with a minimum inter-announcement delay and priority ordering (assertive recording start/stop always takes precedence over polite partial-result updates). Test announcement behaviour on physical iOS and Android devices with VoiceOver/TalkBack enabled as part of the acceptance test plan.
Contingency: If platform differences make reliable queuing impossible, reduce partial-result announcements to a single 'transcription updating' message with debouncing, preserving the critical start/stop announcements. Coordinate with the screen-reader-support feature team to leverage the existing SemanticsServiceFacade patterns already established in the codebase.
The DictationMicrophoneButton must integrate with the dynamic-field-renderer which generates form fields from org-specific schemas at runtime. If the renderer does not expose a stable field metadata API for dictation eligibility checks, the scope guard and button visibility logic will require invasive changes to the report form architecture.
Mitigation & Contingency
Mitigation: Coordinate with the post-session report feature team early in the epic to confirm that dynamic-field-renderer exposes a field metadata interface including field type and sensitivity flags. Add a dictation_eligible flag to the field schema that the renderer passes to DictationMicrophoneButton as a constructor parameter.
Contingency: If the renderer cannot be modified without breaking changes, implement dictation eligibility as a separate lookup against org-field-config-loader using the field key as the lookup identifier, bypassing the renderer integration and keeping the dictation components fully decoupled from the report form architecture.