maspotlighttour/MarketAlly.MASpotlightTour/TourConfiguration.cs

namespace MarketAlly.SpotlightTour.Maui;

/// <summary>
/// Configuration options for the spotlight tour.
/// Use this class to customize timing, sizing, and behavior without modifying component code.
/// </summary>
public class TourConfiguration
{
    /// <summary>
    /// Default configuration instance with standard values.
    /// </summary>
    public static TourConfiguration Default { get; } = new();

    #region Timing Configuration

    /// <summary>
    /// Timeout for scroll operations when ensuring an element is visible.
    /// Default: 1000ms
    /// </summary>
    public int ScrollTimeoutMs { get; set; } = 1000;

    /// <summary>
    /// Delay to allow layout to settle after scrolling.
    /// Default: 50ms
    /// </summary>
    public int LayoutSettleDelayMs { get; set; } = 50;

    /// <summary>
    /// Delay between retry attempts when calculating element bounds.
    /// Default: 100ms
    /// </summary>
    public int BoundsRetryDelayMs { get; set; } = 100;

    /// <summary>
    /// Number of retry attempts for calculating element bounds.
    /// Default: 3
    /// </summary>
    public int BoundsRetryCount { get; set; } = 3;

    /// <summary>
    /// Timeout for waiting for layout to complete.
    /// Default: 500ms
    /// </summary>
    public int LayoutWaitTimeoutMs { get; set; } = 500;

    /// <summary>
    /// Default animation duration in milliseconds.
    /// Default: 250ms
    /// </summary>
    public uint DefaultAnimationDurationMs { get; set; } = 250;

    #endregion

    #region Sizing Configuration

    /// <summary>
    /// Maximum width ratio for callout card relative to container width.
    /// Default: 0.85 (85% of container)
    /// </summary>
    public double CalloutMaxWidthRatio { get; set; } = 0.85;

    /// <summary>
    /// Maximum absolute width for callout card in device-independent units.
    /// Default: 400
    /// </summary>
    public double CalloutMaxWidth { get; set; } = 400;

    /// <summary>
    /// Estimated width of the corner navigator for auto-placement calculations.
    /// Default: 200
    /// </summary>
    public double NavigatorEstimatedWidth { get; set; } = 200;

    /// <summary>
    /// Estimated height of the corner navigator for auto-placement calculations.
    /// Default: 50
    /// </summary>
    public double NavigatorEstimatedHeight { get; set; } = 50;

    /// <summary>
    /// Estimated height of the callout card for auto-placement calculations.
    /// Default: 150
    /// </summary>
    public double CalloutEstimatedHeight { get; set; } = 150;

    /// <summary>
    /// Default margin from screen edges for positioned elements.
    /// Default: 12
    /// </summary>
    public double DefaultMargin { get; set; } = 12;

    /// <summary>
    /// Default corner margin for corner-positioned elements.
    /// Default: 16
    /// </summary>
    public double CornerMargin { get; set; } = 16;

    /// <summary>
    /// Fallback width when element bounds cannot be calculated.
    /// Default: 100
    /// </summary>
    public double FallbackElementWidth { get; set; } = 100;

    /// <summary>
    /// Fallback height when element bounds cannot be calculated.
    /// Default: 50
    /// </summary>
    public double FallbackElementHeight { get; set; } = 50;

    /// <summary>
    /// Maximum width for inline labels.
    /// Default: 300
    /// </summary>
    public double InlineLabelMaxWidth { get; set; } = 300;

    /// <summary>
    /// Default arrow indicator size.
    /// Default: 16
    /// </summary>
    public double ArrowSize { get; set; } = 16;

    #endregion

    #region Auto-Placement Thresholds

    /// <summary>
    /// Minimum overlap threshold (in square pixels) to consider a position acceptable.
    /// Default: 500
    /// </summary>
    public double MinOverlapThreshold { get; set; } = 500;

    /// <summary>
    /// Maximum overlap threshold (in square pixels) before rejecting a position.
    /// Default: 2000
    /// </summary>
    public double MaxOverlapThreshold { get; set; } = 2000;

    /// <summary>
    /// Minimum space required below an element for bottom placement.
    /// Default: 70
    /// </summary>
    public double MinSpaceForPlacement { get; set; } = 70;

    /// <summary>
    /// Minimum space required for side placement (left/right).
    /// Default: 200
    /// </summary>
    public double MinSpaceForSidePlacement { get; set; } = 200;

    /// <summary>
    /// Scale factor for circle spotlight shape relative to element diagonal.
    /// Default: 0.75
    /// </summary>
    public double CircleSpotlightScale { get; set; } = 0.75;

    #endregion

    #region Visual Configuration

    /// <summary>
    /// Default opacity for disabled navigation buttons.
    /// Default: 0.3
    /// </summary>
    public double DisabledButtonOpacity { get; set; } = 0.3;

    /// <summary>
    /// Default dim opacity for the spotlight overlay.
    /// Default: 0.6
    /// </summary>
    public double DefaultDimOpacity { get; set; } = 0.6;

    /// <summary>
    /// Default corner radius for rounded rectangle spotlights.
    /// Default: 8
    /// </summary>
    public double DefaultSpotlightCornerRadius { get; set; } = 8;

    /// <summary>
    /// Default padding around spotlight targets.
    /// Default: 8
    /// </summary>
    public double DefaultSpotlightPadding { get; set; } = 8;

    /// <summary>
    /// Corner radius for callout cards.
    /// Default: 12
    /// </summary>
    public double CalloutCornerRadius { get; set; } = 12;

    /// <summary>
    /// Corner radius for navigation buttons.
    /// Default: 18
    /// </summary>
    public double NavButtonCornerRadius { get; set; } = 18;

    /// <summary>
    /// Size of navigation buttons (width and height).
    /// Default: 36
    /// </summary>
    public double NavButtonSize { get; set; } = 36;

    #endregion

    #region Color Configuration

    /// <summary>
    /// Primary accent color (used for next button, etc.).
    /// Default: #007AFF (iOS blue)
    /// </summary>
    public string PrimaryAccentColor { get; set; } = "#007AFF";

    /// <summary>
    /// Success/completion color (used for done button).
    /// Default: #34C759 (iOS green)
    /// </summary>
    public string SuccessColor { get; set; } = "#34C759";

    /// <summary>
    /// Danger/skip color (used for skip button).
    /// Default: #FF3B30 (iOS red)
    /// </summary>
    public string DangerColor { get; set; } = "#FF3B30";

    /// <summary>
    /// Dark theme background color.
    /// Default: #1C1C1E
    /// </summary>
    public string DarkBackgroundColor { get; set; } = "#1C1C1E";

    /// <summary>
    /// Dark theme border color.
    /// Default: #3A3A3C
    /// </summary>
    public string DarkBorderColor { get; set; } = "#3A3A3C";

    /// <summary>
    /// Dark theme secondary text color.
    /// Default: #ABABAB
    /// </summary>
    public string DarkSecondaryTextColor { get; set; } = "#ABABAB";

    /// <summary>
    /// Light theme border color.
    /// Default: #E5E5EA
    /// </summary>
    public string LightBorderColor { get; set; } = "#E5E5EA";

    #endregion

    #region Animation Configuration

    /// <summary>
    /// Animation configuration for the tour.
    /// If null, uses AnimationConfiguration.Default.
    /// </summary>
    public Animations.AnimationConfiguration? AnimationConfig { get; set; }

    /// <summary>
    /// Gets the effective animation configuration.
    /// </summary>
    public Animations.AnimationConfiguration EffectiveAnimations =>
        AnimationConfig ?? Animations.AnimationConfiguration.Default;

    #endregion

    /// <summary>
    /// Creates a copy of this configuration.
    /// </summary>
    public TourConfiguration Clone()
    {
        var clone = (TourConfiguration)MemberwiseClone();
        clone.AnimationConfig = AnimationConfig?.Clone();
        return clone;
    }
}