Implement disabled-state visual feedback
epic-expense-type-selection-user-interface-task-005 — Render visually distinct disabled states on expense type cards when the mutual exclusion rule engine marks a type as incompatible. Disabled cards must be non-interactive (ignore taps), show reduced opacity, and display an explanatory tooltip or inline label explaining why the option is unavailable.
Acceptance Criteria
Technical Requirements
Execution Context
Tier 4 - 323 tasks
Can start after Tier 3 completes
Implementation Notes
Extend ExpenseTypeOptionCard to accept an optional String? disabledReason parameter. When isDisabled is true and disabledReason is non-null, render the reason either as a small Text widget below the label or wrap the card in a Tooltip widget (prefer inline label for visibility since tooltips require a long-press on mobile which is a discoverability risk). Use AnimatedOpacity with a 150ms duration to transition between enabled and disabled states.
Do not use IgnorePointer alone to block taps — also set the Semantics widget's enabled: false to prevent screen readers from focusing disabled cards. The disabledReason strings are produced by the mutual exclusion rule engine in the BLoC layer and passed through the ExpenseSelectionState; this widget only renders what it receives. For the HLF use case, the typical reason will be something like 'Not compatible with selected kilometer allowance'.
Testing Requirements
Widget tests: (1) verify disabled card ignores tap callbacks, (2) verify opacity wrapper applies 0.38 opacity value, (3) verify reason string appears in the widget tree when provided, (4) verify Semantics hint contains the reason string, (5) golden test disabled card with reason vs disabled card without reason. Also test the animation: use tester.pump(Duration(milliseconds: 200)) and verify the opacity value mid-transition. Manual test: confirm the reason tooltip/label is legible under system-level display accessibility settings (large text, high contrast mode).
If the expense calculation preview subscribes to the full BLoC state stream, every unrelated state property change (e.g. a loading flag toggle) triggers a widget rebuild. With complex card animations for the disabled-state transition, this could cause frame drops on low-end Android devices used by some peer mentors.
Mitigation & Contingency
Mitigation: Use select() on the Riverpod provider to subscribe only to the specific state slice each widget needs; write a performance test asserting rebuild count on a rapid sequence of toggle events.
Contingency: If jank is detected in device testing, replace animated disabled-state transitions with instant opacity changes and defer animation polish to a follow-up sprint.
The disabled card state requires a specific contrast-safe colour combination that communicates unavailability without relying solely on colour (WCAG 1.4.1). If the current design token palette does not include a disabled-state token with sufficient contrast for text on the disabled background, the widget will either fail WCAG AA or require a last-minute design token addition that could break other components.
Mitigation & Contingency
Mitigation: Audit the existing design token manifest for disabled-state tokens at the start of the epic; if missing, raise with the design lead and add a contrast-validated token before widget implementation begins.
Contingency: If no design review is available, use the established --color-text-disabled and --color-surface-disabled tokens with an added strikethrough or lock icon to satisfy WCAG 1.4.1 non-colour requirement, and document the deviation for design review.