Wizard State Manager
Component Detail
Description
BLoC-based state manager for all multi-step wizards, implementing pause-and-resume semantics. Persists partial wizard state locally so users can abandon and return without losing progress. Drives the progress indicator and back-navigation behaviour.
wizard-state-manager
Summaries
The Wizard State Manager enables users to start a multi-step process — such as activity logging or reporting — pause at any point due to real-world interruptions, and resume later without losing their progress. This pause-and-resume capability is a significant quality-of-life feature for users managing complex workflows in interruption-prone mobile environments. Reducing the friction of form abandonment directly increases completion rates for key user journeys, translating to more complete and higher-quality data submissions. For organizations whose value depends on accurate activity or report data, higher completion rates have measurable operational impact.
The component also reduces support burden by eliminating a major source of user complaints about lost work.
This is a medium-complexity shared BLoC component with a single dependency on the Wizard Draft Repository, which must be delivered first to unblock integration. Because it is shared across all multi-step wizards in the application, changes to its API or event model will affect every feature using a wizard flow — change management and thorough regression testing are essential for any future modification. The BLoC pattern requires developer familiarity with reactive state management in Flutter; budget onboarding time if this is new to the team. Testing must cover pause-and-resume round-trips, back-navigation accuracy, draft expiry edge cases, and concurrent wizard instances, across both the activity and report data models that this component manages.
The Wizard State Manager is implemented as a BLoC exposing: `nextStep(answers)`, `previousStep()`, `saveDraft()`, `restoreDraft(wizardId)`, `clearDraft(wizardId)`, `getCurrentStep(): WizardStep`, and `getProgress(): WizardProgress`. State mutations emit events only on explicit user actions — no auto-advance logic — enforcing the cognitive accessibility contract at the state layer. On every `nextStep` call the BLoC delegates to `WizardDraftRepository.saveDraft()` to persist partial answers keyed by wizard ID and user ID, enabling seamless resume. The BLoC consumes `activity` and `report` data models, so those type definitions must be available as dependencies at compile time.
As a shared component it should be injected via a scoped provider at the wizard feature level rather than globally, to avoid state leakage between concurrent wizard instances.
Responsibilities
- Track current step, answers, and completion status across wizard lifecycle
- Persist draft state to local storage on every step change
- Restore draft state on wizard re-entry
- Emit step-change events only on explicit user action, never automatically
Interfaces
WizardStateBloc({wizardId})
nextStep(answers)
previousStep()
saveDraft()
restoreDraft(wizardId)
clearDraft(wizardId)
getCurrentStep(): WizardStep
getProgress(): WizardProgress