Beep Wizard System

Overview

The Beep Wizard System is architected as a decoupled core-engine / UI-host pair:

• WizardManager — static façade; creates and shows wizards in one call.
• WizardInstance — the runtime engine; owns navigation, validation, and state. Contains no UI code.
• WizardFormFactory — instantiates the correct form host for the chosen WizardStyle.
• IWizardFormHost — interface that all four form types implement; keeps the engine UI-agnostic.
• WizardContext — typed key/value data bus shared across all steps.

Architecture

// Layer overview
WizardManager            // static façade — create / show / close wizards
  └─ WizardInstance      // core engine: navigation, validation, state, events
       ├─ WizardConfig   // immutable construction config + step list
       ├─ WizardContext  // typed key/value data shared between steps
       └─ IWizardFormHost─┬─ HorizontalStepperWizardForm
                          ├─ VerticalStepperWizardForm
                          ├─ MinimalWizardForm
                          └─ CardsWizardForm

Decoupling principle

WizardInstance calls only IWizardFormHost methods (UpdateUI, ShowValidationError, GetContentPanel, etc.). Swapping a visual style at creation time is the only change needed — no engine logic changes.

Wizard Styles (WizardStyle enum)

Key Classes & Models

WizardConfig

All wizard settings passed to WizardManager.CreateWizard(). Immutable after creation.

WizardStep

Each step in the Config.Steps list.

WizardContext (Data Bus)

A typed key/value dictionary shared across all steps. The engine sets CurrentStepIndex and TotalSteps; your code reads/writes all other keys.

Enumerations

StepState

WizardResult

WizardManager (Entry Point)

WizardManager is a static class that acts as the single entry point for creation, display, and lifecycle management.

WizardInstance Events

WizardInstance navigation methods

Validation

Validators are attached to a WizardStep.Validators list. They implement IWizardValidator and are called automatically by the engine when Next / Finish is clicked. The first failing validator blocks navigation and shows the error inline.

Built-in Validators

ValidationPatterns constants

ValidationPatterns.Email    // ^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$
ValidationPatterns.Phone    // ^\+?[\d\s\-()]{10,}$
ValidationPatterns.Url      // ^https?://[\w\-]+(\.[\w\-]+)+[/#?]?.*$
ValidationPatterns.ZipCode  // ^\d{5}(-\d{4})?$
ValidationPatterns.Integer  // ^\-?\d+$
ValidationPatterns.Decimal  // ^\-?\d+(\.\d+)?$

WizardValidationResult

// Factory methods — use these in custom validators
WizardValidationResult.Success()
WizardValidationResult.Error("Error message")
WizardValidationResult.Error("Error message", "contextKey")  // focuses specific field

Delegate-based quick validation (no validator class needed)

new WizardStep
{
    Key = "terms",
    Title = "Terms",
    CanNavigateNext = ctx =>
        ctx.GetValue<bool>("termsAccepted", false),
}

Step Templates

Pre-built step UserControl classes that implement IWizardStepContent. Derive from WizardStepTemplateBase to get automatic OnStepEnter / OnStepLeave lifecycle and ValidationStateChanged event.

Creating a custom step template

public class AccountStep : WizardStepTemplateBase
{
    private TextBox _emailBox;

    public AccountStep()
    {
        InitializeComponent();   // your designer code
    }

    protected override void LoadData()
    {
        // called on enter — populate UI from context
        _emailBox.Text = Context.GetValue<string>("email", "");
    }

    protected override void SaveData()
    {
        // called on leave — persist UI back to context
        Context.SetValue("email", _emailBox.Text.Trim());
    }

    public override WizardValidationResult Validate()
    {
        if (string.IsNullOrWhiteSpace(_emailBox.Text))
            return WizardValidationResult.Error("Email is required", "email");
        return WizardValidationResult.Success();
    }
}

WizardFormFactory — Custom Styles

Register a factory function to provide a completely custom form for any WizardStyle value:

// Register a branded corporate wizard form
WizardFormFactory.RegisterFactory(
    WizardStyle.Cards,
    instance => new MyCorporateWizardForm(instance)
);

// Now all Cards style wizards use your custom form
WizardManager.ShowWizard(new WizardConfig
{
    Style = WizardStyle.Cards,
    // ...
});

Animations

WizardHelpers provides two built-in transitions used by the form hosts:

Disable all animations globally: WizardManager.EnableAnimations = false;

Quick Start

// Minimal 3-step wizard shown as modal dialog
var result = WizardManager.ShowWizard(new WizardConfig
{
    Title       = "New Connection",
    Style       = WizardStyle.HorizontalStepper,
    AllowCancel = true,

    Steps = new List<WizardStep>
    {
        new WizardStep
        {
            Key     = "welcome",
            Title   = "Welcome",
            Content = new WelcomeStepTemplate
            {
                WelcomeTitle   = "New Connection Wizard",
                WelcomeMessage = "This wizard will guide you through setting up a data connection."
            }
        },
        new WizardStep
        {
            Key     = "connection",
            Title   = "Connection Details",
            Content = new ConnectionDetailsStep(),      // your UserControl
            Validators = new List<IWizardValidator>
            {
                new RequiredFieldValidator("serverName", "database"),
                new RequiredFieldValidator("username")
            }
        },
        new WizardStep
        {
            Key          = "summary",
            Title        = "Summary",
            Content      = new SummaryStepTemplate
            {
                SummaryTitle   = "Review Connection",
                SummaryBuilder = ctx =>
                    $"Server: {ctx.GetValue<string>("serverName")}\n" +
                    $"Database: {ctx.GetValue<string>("database")}"
            },
            NextButtonText = "Finish"
        }
    },

    OnComplete = ctx =>
    {
        var server = ctx.GetValue<string>("serverName");
        var db     = ctx.GetValue<string>("database");
        CreateConnection(server, db);
    }
}, this);   // owner window

if (result == DialogResult.OK)
    MessageBox.Show("Connection created!");

Advanced Examples

Hooking events before display

var instance = WizardManager.CreateWizard(new WizardConfig { /* ... */ });

instance.StepChanging += (s, e) =>
{
    if (e.ToIndex == 2 && !PreFlightCheck())
    {
        e.Cancel = true;
        MessageBox.Show("Please complete the pre-flight check first.");
    }
};

instance.StepChanged += (s, e) =>
    statusBar.Text = $"Step {e.ToIndex + 1} of {instance.Config.Steps.Count}";

instance.Completed += (s, e) =>
    SaveWizardData(e.Context);

instance.ShowDialog(this);

Async step callbacks

new WizardStep
{
    Key   = "validate",
    Title = "Validate Connection",

    OnEnterAsync = async ctx =>
    {
        // runs when step becomes active — e.g. load defaults from API
        var defaults = await ApiClient.GetConnectionDefaultsAsync();
        ctx.SetValue("defaultServer", defaults.Server);
    },

    OnLeaveAsync = async ctx =>
    {
        // runs when navigating away — e.g. persist/validate server-side
        var server = ctx.GetValue<string>("serverName");
        bool ok = await ApiClient.TestConnectionAsync(server);
        if (!ok)
            throw new InvalidOperationException("Cannot reach server");  // blocks navigation
    }
}

Conditional step skipping

new WizardStep
{
    Key        = "advancedOptions",
    Title      = "Advanced Options",
    IsOptional = true,
    ShouldSkip = ctx => !ctx.GetValue<bool>("showAdvanced", false),
    Content    = new AdvancedOptionsStep()
}

Custom CardStyle wizard with branded header

WizardFormFactory.RegisterFactory(WizardStyle.Cards, inst => new BrandedWizardForm(inst));

WizardManager.ShowWizard(new WizardConfig
{
    Style       = WizardStyle.Cards,
    Title       = "Onboarding",
    Size        = new Size(1000, 700),
    AllowSkip   = true,
    ShowHelp    = true,
    HelpUrl     = "https://docs.example.com/onboarding",
    Steps       = /* ... */
});

Reading collected data after completion

var instance = WizardManager.CreateWizard(config);
instance.ShowDialog(this);

if (instance.Result == WizardResult.Completed)
{
    var ctx = instance.Context;
    var name     = ctx.GetValue<string>("firstName")  + " " + ctx.GetValue<string>("lastName");
    var plan     = ctx.GetValue<string>("selectedPlan", "Free");
    var accepted = ctx.GetValue<bool>("termsAccepted", false);
    // process...
}

Best Practices

• Use WizardManager.ShowWizard() for fire-and-forget wizards. Use CreateWizard() only when you need to hook events before display.
• Store all cross-step data in WizardContext — do not use static fields or class-level variables. Context data is available in the OnComplete callback and in WizardInstance.Context after the dialog closes.
• Prefer Step.Validators over CanNavigateNext delegates when you want inline error messages. CanNavigateNext silently blocks navigation without a user-facing message.
• Use WizardStepTemplateBase for custom step controls — the LoadData() / SaveData() pattern keeps concerns clean.
• Mark optional steps with IsOptional=true and enable AllowSkip in WizardConfig to give users an explicit Skip button.
• Use ShouldSkip for programmatic conditional steps (e.g. skip billing step for Free plans). This is automatic and invisible to the user.
• Prefer OnEnterAsync / OnLeaveAsync for I/O (API calls, DB queries). The engine awaits the task before updating the UI.
• Disable animations during automated tests: WizardManager.EnableAnimations = false;
• Always pass an owner window to ShowWizard(config, this) so the dialog centres correctly.
• Register a custom factory once at startup in WizardFormFactory.RegisterFactory() to globally change the UI for a given style.