Integrate HelpContentRegistry with InlineContextualHelpWidget

epic-cognitive-accessibility-wizard-ui-task-009 — Wire InlineContextualHelpWidget to the HelpContentRegistry (from the foundation epic) so that each widget instance receives a help key, resolves it to localised help text at build time, and displays that text when expanded. If the registry returns null for an unknown key, hide the widget entirely rather than showing an empty panel. Support hot-swap of help content without widget rebuild.

high priority low complexity integration pending frontend specialist Tier 1

Acceptance Criteria

InlineContextualHelpWidget accepts a required `helpKey` String and an optional `registry` parameter for dependency injection

At build time, the widget calls `registry.resolve(helpKey)` synchronously and uses the returned String as `helpText`

When `registry.resolve(helpKey)` returns null (unknown key), the widget renders `SizedBox.shrink()` — no icon, no panel, no empty space beyond zero height

When `registry.resolve(helpKey)` returns a non-null String, the widget behaves exactly as defined in task-008 (icon + expand/collapse)

Hot-swap of help content is supported: if the registry's content changes (e.g., locale switch), the widget updates without requiring a full widget rebuild — implemented via `ValueListenable<Map>` or equivalent observable registry

If the registry content changes while the widget is in the expanded state and the new content for this key is null, the widget collapses and hides itself

If the registry content changes while the widget is in the expanded state and the new content differs in text, the expanded panel updates text in-place without collapsing

Widget does not hold a strong reference to the registry that would prevent garbage collection

The `helpKey` is never rendered in the UI — it is an internal lookup key only

Integration compiles and functions correctly with both the real HelpContentRegistry and a stub/mock

Technical Requirements

frameworks

Flutter

flutter_test

apis

HelpContentRegistry (internal foundation epic API)

data models

accessibility_preferences

performance requirements

Registry lookup is O(1) and synchronous — no async gap before help text is available

Hot-swap update triggers at most one setState call per content change — no cascading rebuilds

security requirements

Help text content is sourced from the registry only — no interpolation of user-controlled strings

Registry must not expose internal system paths, API keys, or raw error details in help text

ui components

InlineContextualHelpWidget

Execution Context

Execution Tier

Tier 1

Tier 1 - 540 tasks

Can start after Tier 0 completes

View Full Execution Plan

Implementation Notes

The cleanest pattern for hot-swap without forced rebuild is to have HelpContentRegistry expose a `ValueListenable>`. In InlineContextualHelpWidget, use a `ValueListenableBuilder` wrapping the widget body — it re-renders only when the map changes and is more efficient than `addListener`/`removeListener` in initState/dispose. The null-key hide behaviour should be implemented as: `if (helpText == null) return const SizedBox.shrink();` at the top of the `ValueListenableBuilder` builder function, before returning the actual widget structure. This ensures the Semantics tree is completely clean when there is no content.

For the dependency injection pattern, default the registry parameter to `HelpContentRegistry.instance` in the constructor — this keeps call sites clean while keeping the widget fully testable.

Testing Requirements

Write widget tests using a stub HelpContentRegistry: (1) known key renders icon and help text; (2) unknown key renders nothing (find.byType(InlineContextualHelpWidget) returns a widget but find.byType(Icon) finds nothing); (3) hot-swap test — start with known key, call `registry.update(key, null)`, pump, assert widget hides; (4) hot-swap text update — start expanded, update registry text, pump, assert new text visible without collapsing. Use a `ValueNotifier>` as the stub registry backing store to simulate hot-swap. All tests must pass with `flutter test`.

Component

Inline Contextual Help Widget

ui low

Dependencies (1)

Implement InlineContextualHelpWidget as a stateful Flutter widget with a collapsed default state showing a labelled help icon (question mark) and an expanded state showing the full help text. Use AnimatedContainer for smooth expand/collapse. Apply Semantics with expandedHint and collapsedHint to communicate state changes to screen readers. Position widget inline within form fields without disrupting tab order. epic-cognitive-accessibility-wizard-ui-task-008

Epic Risks (4)

high impact medium prob technical

The WizardStateManager BLoC must guarantee that step transitions only occur on explicit user action, never automatically. Subtle reactive patterns in Bloc (e.g. stream listeners triggering add() calls) could inadvertently auto-advance the wizard, violating the core cognitive accessibility rule and creating a regression that is difficult to detect without dedicated tests.

Mitigation & Contingency

Mitigation: Write a dedicated unit test that subscribes to the BLoC stream and asserts no StepChanged event is emitted for 5 seconds after a state update, without an explicit user-sourced event being dispatched. Make this test part of the CI gate for the WizardStateManager.

Contingency: If an auto-advance regression is discovered post-integration, introduce a mandatory UserActionToken parameter on all step-transition events so the BLoC can structurally refuse transitions that do not originate from a user gesture handler.

medium impact medium prob integration

The ConfirmBeforeSubmitScreen requires deep-linking back to specific wizard steps for corrections. Implementing bidirectional navigation within a multi-step wizard while preserving all previously entered state is architecturally non-trivial and may conflict with the existing StatefulShellRoute navigation setup described in the app architecture.

Mitigation & Contingency

Mitigation: Design the ConfirmBeforeSubmitScreen's back-navigation links to dispatch a GoToStep event on the WizardStateManager rather than using GoRouter's pop() chain. This keeps navigation state entirely in the BLoC and avoids coupling to the router's stack semantics.

Contingency: If BLoC-driven step navigation proves incompatible with the router, implement the correction flow as a dedicated sub-route that pre-populates its form from the WizardStateManager's current draft, then merges the edited field back into the draft on completion before returning to the confirm screen.

medium impact medium prob technical

The CognitiveAccessibilityAudit utility must inspect live widget trees for violations such as icon-only buttons. Flutter's widget tree inspection APIs are available in test mode but have limitations in identifying semantic intent (e.g. distinguishing a decorative icon from a navigation button). False negatives could give a false sense of compliance.

Mitigation & Contingency

Mitigation: Augment the audit with a convention-based approach: require all navigation buttons to use a named wrapper widget (e.g. LabelledNavigationButton) that the audit can detect by type, rather than relying solely on widget-tree semantics analysis.

Contingency: If widget-tree detection proves insufficiently reliable, scope the CognitiveAccessibilityAudit to route-configuration analysis (verifying back navigation availability per route) and static analysis of wizard step count definitions via the CognitiveLoadRuleEngine, which provides deterministic results.

low impact high prob scope

The InlineContextualHelpWidget sources content from a bundled JSON asset via the HelpContentRegistry. If help texts are missing for newly added screens or fields (a likely scenario as the 61-feature app grows), the widget silently shows nothing, degrading the accessibility experience without any visible failure.

Mitigation & Contingency

Mitigation: Integrate a CognitiveAccessibilityAudit check that verifies every registered (screenId, fieldId) pair that requests help has a corresponding entry in the HelpContentRegistry bundle. Run this check in CI as part of the audit report.

Contingency: Add a debug-mode overlay that highlights fields with missing help entries using a visible warning indicator, making coverage gaps immediately obvious to developers during local development before they reach CI.

Quick Links

All Tasks Execution Plan