maspotlighttour/MarketAlly.MASpotlightTour/Enums.cs

namespace MarketAlly.SpotlightTour.Maui;

/// <summary>
/// Specifies the visual theme for the tour components.
/// </summary>
public enum TourTheme
{
    /// <summary>
    /// Light theme with white backgrounds and dark text.
    /// </summary>
    Light,

    /// <summary>
    /// Dark theme with dark backgrounds and light text.
    /// </summary>
    Dark,

    /// <summary>
    /// Automatically follows the system theme.
    /// </summary>
    System
}

/// <summary>
/// Specifies where the callout card is positioned relative to the spotlight.
/// </summary>
public enum CalloutPlacement
{
    /// <summary>
    /// Automatically determine placement based on available space.
    /// </summary>
    Auto,

    /// <summary>
    /// Position callout above the spotlight.
    /// </summary>
    Top,

    /// <summary>
    /// Position callout below the spotlight.
    /// </summary>
    Bottom,

    /// <summary>
    /// Position callout to the left of the spotlight.
    /// </summary>
    Left,

    /// <summary>
    /// Position callout to the right of the spotlight.
    /// </summary>
    Right
}

/// <summary>
/// Specifies the shape of the spotlight cutout.
/// </summary>
public enum SpotlightShape
{
    /// <summary>
    /// Rectangular cutout matching the element bounds.
    /// </summary>
    Rectangle,

    /// <summary>
    /// Rounded rectangle cutout with configurable corner radius.
    /// </summary>
    RoundedRectangle,

    /// <summary>
    /// Circular cutout centered on the element.
    /// </summary>
    Circle
}

/// <summary>
/// Specifies behavior when the user taps on the spotlighted element.
/// </summary>
public enum SpotlightTapBehavior
{
    /// <summary>
    /// Tapping the spotlight does nothing; only nav buttons work.
    /// </summary>
    None,

    /// <summary>
    /// Tapping the spotlight advances to the next step.
    /// </summary>
    Advance,

    /// <summary>
    /// Tapping the spotlight closes the tour.
    /// </summary>
    Close,

    /// <summary>
    /// Allow interaction with the underlying element (pass-through).
    /// </summary>
    AllowInteraction
}

/// <summary>
/// Specifies the corner position for the navigator control.
/// </summary>
public enum CornerNavigatorPlacement
{
    /// <summary>
    /// Top-left corner of the screen.
    /// </summary>
    TopLeft,

    /// <summary>
    /// Top-right corner of the screen.
    /// </summary>
    TopRight,

    /// <summary>
    /// Bottom-left corner of the screen.
    /// </summary>
    BottomLeft,

    /// <summary>
    /// Bottom-right corner of the screen.
    /// </summary>
    BottomRight,

    /// <summary>
    /// Automatically positions in the corner that least overlaps with the highlighted element.
    /// </summary>
    Auto
}

/// <summary>
/// Specifies the positioning strategy for the callout card.
/// </summary>
public enum CalloutPositionMode
{
    /// <summary>
    /// Callout follows/positions relative to the highlighted element.
    /// Uses CalloutPlacement to determine which side (Auto, Top, Bottom, Left, Right).
    /// </summary>
    Following,

    /// <summary>
    /// Callout is fixed in a specific screen corner.
    /// Uses CalloutCorner to determine which corner.
    /// </summary>
    FixedCorner,

    /// <summary>
    /// Callout automatically positions in the screen corner that least
    /// interferes with the highlighted element.
    /// </summary>
    AutoCorner
}

/// <summary>
/// Specifies which screen corner for fixed/auto corner positioning.
/// </summary>
public enum CalloutCorner
{
    /// <summary>
    /// Top-left corner of the screen.
    /// </summary>
    TopLeft,

    /// <summary>
    /// Top-right corner of the screen.
    /// </summary>
    TopRight,

    /// <summary>
    /// Bottom-left corner of the screen.
    /// </summary>
    BottomLeft,

    /// <summary>
    /// Bottom-right corner of the screen.
    /// </summary>
    BottomRight
}

/// <summary>
/// Specifies the display mode for the onboarding tour.
/// </summary>
public enum TourDisplayMode
{
    /// <summary>
    /// Full experience: dimmed overlay + spotlight cutout + callout card with nav buttons.
    /// </summary>
    SpotlightWithCallout,

    /// <summary>
    /// Callout cards only - no dimming, just floating callouts that point to elements.
    /// Good for light-touch guidance without blocking interaction.
    /// </summary>
    CalloutOnly,

    /// <summary>
    /// Dimmed overlay with spotlight cutouts, but titles/descriptions shown as
    /// inline labels positioned around the spotlight (no callout card).
    /// Use corner navigator for navigation.
    /// </summary>
    SpotlightWithInlineLabel
}

/// <summary>
/// Specifies how a tour ended.
/// </summary>
public enum TourResult
{
    /// <summary>
    /// The tour completed successfully (user went through all steps).
    /// </summary>
    Completed,

    /// <summary>
    /// The tour was skipped by the user.
    /// </summary>
    Skipped,

    /// <summary>
    /// The tour was cancelled programmatically.
    /// </summary>
    Cancelled,

    /// <summary>
    /// No steps were found to show.
    /// </summary>
    NoSteps
}