Define field row data model and validation state enum
epic-bufdir-report-preview-ui-components-task-001 — Define the Dart data model for BufdirFieldRowData including label, value, validationState enum (normal, warning, anomaly), tooltip text, and field identifier. This model will be consumed by BufdirFieldRowWidget and produced by BufdirPreviewService. Ensure the model is immutable and equatable.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use the equatable package for == and hashCode to avoid boilerplate errors. The validationState field should serialize to/from a lowercase string in JSON ('normal', 'warning', 'anomaly') matching what BufdirPreviewService returns from Supabase. Prefer a static Map
Place the enum definition in the same file as the model for colocation. This model is a foundational dependency for tasks 002, 003, 004, and 005 — ensure the API is stable before those tasks begin.
Testing Requirements
Write unit tests in test/features/bufdir/models/bufdir_field_row_data_test.dart. Cover: (1) equality for two identical instances; (2) inequality when any single field differs; (3) copyWith preserves unchanged fields; (4) fromJson/toJson round-trip for validationState='normal', 'warning', 'anomaly'; (5) null tooltipText serializes to null in JSON and deserializes correctly. Use flutter_test package. No widget tests needed — pure Dart model.
Implementing the tap-to-scroll-and-focus behavior from the validation banner to a specific field row in a long scrollable list is complex in Flutter. If focus management is incorrectly implemented, VoiceOver users who navigate to the banner and select an issue will not be moved to the relevant field row, breaking the accessibility workflow and violating WCAG 2.4.3 (Focus Order).
Mitigation & Contingency
Mitigation: Use BufdirAccessibilityUtils focus management utilities (built in the foundation epic) with explicit GlobalKey-based scroll anchors on each field row. Test with a real iOS device running VoiceOver during widget development, not only in the Flutter accessibility inspector.
Contingency: If programmatic scroll-to-focus cannot be reliably achieved before the TestFlight deadline, fall back to a navigation approach where tapping a banner issue opens a modal detail sheet for that field row rather than scrolling in place, and file a follow-up ticket for the inline scroll implementation.
The validation summary banner must reactively update its issue count as underlying aggregated data changes (e.g., if the coordinator has navigated away and data was refreshed). If the banner's Riverpod provider is not correctly scoped, it may display stale issue counts or fail to disappear when all issues are resolved, eroding coordinator trust in the validation system.
Mitigation & Contingency
Mitigation: Drive the banner exclusively from the same Riverpod provider that powers the full preview model — do not maintain a separate local state for issue counts. Write a widget test that simulates a data refresh mid-review and asserts the banner updates within one frame.
Contingency: If stale state reaches production, add a manual refresh button to the banner as a short-term workaround while the provider scoping is corrected in the next release cycle.