dotmax/color/

scheme_builder.rs

//! Builder pattern for creating custom color schemes.
//!
//! This module provides [`ColorSchemeBuilder`] for creating custom color schemes with
//! fine-grained control over intensity-to-color mapping. Unlike the predefined schemes,
//! custom schemes allow precise placement of color stops at specific intensity values.
//!
//! # Overview
//!
//! A color scheme maps intensity values (0.0 to 1.0) to colors. The builder pattern
//! enables creating gradients with color stops at arbitrary intensity positions,
//! automatically sorting and validating the configuration.
//!
//! # Examples
//!
//! ## Basic Builder Usage
//!
//! ```
//! use dotmax::color::scheme_builder::ColorSchemeBuilder;
//! use dotmax::Color;
//!
//! let scheme = ColorSchemeBuilder::new("fire")
//!     .add_color(0.0, Color::rgb(0, 0, 0))      // Black at 0%
//!     .add_color(0.3, Color::rgb(255, 0, 0))    // Red at 30%
//!     .add_color(0.7, Color::rgb(255, 165, 0))  // Orange at 70%
//!     .add_color(1.0, Color::rgb(255, 255, 0))  // Yellow at 100%
//!     .build()
//!     .unwrap();
//!
//! // Sample the scheme
//! let color_at_half = scheme.sample(0.5);
//! ```
//!
//! ## Colors in Any Order
//!
//! Colors can be added in any order - they are automatically sorted by intensity:
//!
//! ```
//! use dotmax::color::scheme_builder::ColorSchemeBuilder;
//! use dotmax::Color;
//!
//! let scheme = ColorSchemeBuilder::new("shuffled")
//!     .add_color(1.0, Color::white())           // Added last but highest intensity
//!     .add_color(0.0, Color::black())           // Added first but lowest intensity
//!     .add_color(0.5, Color::rgb(128, 128, 128)) // Middle
//!     .build()
//!     .unwrap();
//!
//! // Sampling works correctly regardless of insertion order
//! assert_eq!(scheme.sample(0.0).r, 0);   // Black
//! assert_eq!(scheme.sample(1.0).r, 255); // White
//! ```
//!
//! ## Validation Errors
//!
//! The builder validates the configuration and returns descriptive errors:
//!
//! ```
//! use dotmax::color::scheme_builder::ColorSchemeBuilder;
//! use dotmax::Color;
//!
//! // Error: Need at least 2 colors
//! let result = ColorSchemeBuilder::new("single")
//!     .add_color(0.5, Color::white())
//!     .build();
//! assert!(result.is_err());
//!
//! // Error: Intensity out of range
//! let result = ColorSchemeBuilder::new("invalid")
//!     .add_color(-0.5, Color::black())  // Invalid!
//!     .add_color(1.5, Color::white())   // Invalid!
//!     .build();
//! assert!(result.is_err());
//! ```
//!
//! # Performance
//!
//! - Builder operations allocate during construction
//! - Built schemes have identical performance to predefined schemes
//! - Target: <100ns per `sample()` call on built schemes

use crate::color::schemes::ColorScheme;
use crate::error::DotmaxError;
use crate::grid::Color;

/// A builder for creating custom color schemes with intensity-based color stops.
///
/// `ColorSchemeBuilder` provides a fluent API for defining color gradients where
/// each color is associated with a specific intensity value (0.0 to 1.0). The
/// builder handles sorting, validation, and construction of the final [`ColorScheme`].
///
/// # Builder Pattern
///
/// The builder follows a standard pattern:
/// 1. Create with [`ColorSchemeBuilder::new`]
/// 2. Add colors with [`add_color`](ColorSchemeBuilder::add_color)
/// 3. Build with [`build`](ColorSchemeBuilder::build)
///
/// # Examples
///
/// ```
/// use dotmax::color::scheme_builder::ColorSchemeBuilder;
/// use dotmax::Color;
///
/// // Create a "sunset" gradient
/// let scheme = ColorSchemeBuilder::new("sunset")
///     .add_color(0.0, Color::rgb(255, 100, 0))   // Orange
///     .add_color(0.5, Color::rgb(255, 0, 100))   // Pink
///     .add_color(1.0, Color::rgb(100, 0, 255))   // Purple
///     .build()?;
///
/// // Use the scheme
/// let mid_color = scheme.sample(0.5);
/// # Ok::<(), dotmax::DotmaxError>(())
/// ```
#[derive(Debug, Clone)]
pub struct ColorSchemeBuilder {
    /// Human-readable name for the scheme
    name: String,
    /// Color stops as (intensity, color) pairs
    stops: Vec<(f32, Color)>,
}

impl ColorSchemeBuilder {
    /// Create a new color scheme builder with the given name.
    ///
    /// The builder starts with no color stops. Use [`add_color`](ColorSchemeBuilder::add_color)
    /// to add color stops before calling [`build`](ColorSchemeBuilder::build).
    ///
    /// # Arguments
    ///
    /// * `name` - Human-readable name for the scheme (e.g., "fire", "ocean", "brand")
    ///
    /// # Examples
    ///
    /// ```
    /// use dotmax::color::scheme_builder::ColorSchemeBuilder;
    ///
    /// let builder = ColorSchemeBuilder::new("my_gradient");
    /// ```
    #[must_use]
    pub fn new(name: impl Into<String>) -> Self {
        Self {
            name: name.into(),
            stops: Vec::new(),
        }
    }

    /// Add a color stop at the specified intensity.
    ///
    /// Color stops define the gradient by mapping intensity values to colors.
    /// Colors can be added in any order - they will be automatically sorted
    /// by intensity when [`build`](ColorSchemeBuilder::build) is called.
    ///
    /// # Arguments
    ///
    /// * `intensity` - Intensity value from 0.0 (low) to 1.0 (high)
    /// * `color` - The RGB color at this intensity
    ///
    /// # Returns
    ///
    /// Returns `self` for method chaining.
    ///
    /// # Note
    ///
    /// Intensity validation happens during [`build`](ColorSchemeBuilder::build),
    /// not during `add_color`. This allows for flexible construction patterns.
    ///
    /// # Examples
    ///
    /// ```
    /// use dotmax::color::scheme_builder::ColorSchemeBuilder;
    /// use dotmax::Color;
    ///
    /// let builder = ColorSchemeBuilder::new("gradient")
    ///     .add_color(0.0, Color::black())
    ///     .add_color(0.5, Color::rgb(128, 128, 128))
    ///     .add_color(1.0, Color::white());
    /// ```
    #[must_use]
    pub fn add_color(mut self, intensity: f32, color: Color) -> Self {
        self.stops.push((intensity, color));
        self
    }

    /// Build the color scheme, validating the configuration.
    ///
    /// This method validates all color stops and constructs the final [`ColorScheme`].
    /// Color stops are automatically sorted by intensity in ascending order.
    ///
    /// # Validation Rules
    ///
    /// The following conditions result in errors:
    ///
    /// - **Less than 2 color stops**: Returns [`DotmaxError::InvalidColorScheme`]
    /// - **Intensity out of range** (< 0.0 or > 1.0): Returns [`DotmaxError::InvalidIntensity`]
    /// - **Duplicate intensity values**: Returns [`DotmaxError::InvalidColorScheme`]
    ///
    /// # Returns
    ///
    /// * `Ok(ColorScheme)` - A valid color scheme ready for use
    /// * `Err(DotmaxError)` - If validation fails
    ///
    /// # Examples
    ///
    /// ```
    /// use dotmax::color::scheme_builder::ColorSchemeBuilder;
    /// use dotmax::Color;
    ///
    /// // Successful build
    /// let scheme = ColorSchemeBuilder::new("valid")
    ///     .add_color(0.0, Color::black())
    ///     .add_color(1.0, Color::white())
    ///     .build()?;
    ///
    /// // Failed build: not enough colors
    /// let result = ColorSchemeBuilder::new("invalid")
    ///     .add_color(0.5, Color::white())
    ///     .build();
    /// assert!(result.is_err());
    /// # Ok::<(), dotmax::DotmaxError>(())
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`DotmaxError::InvalidColorScheme`] if:
    /// - Fewer than 2 color stops are defined
    /// - Two or more color stops have the same intensity value
    ///
    /// Returns [`DotmaxError::InvalidIntensity`] if:
    /// - Any intensity value is less than 0.0 or greater than 1.0
    pub fn build(mut self) -> Result<ColorScheme, DotmaxError> {
        // Validate: at least 2 color stops required
        if self.stops.len() < 2 {
            return Err(DotmaxError::InvalidColorScheme(
                "at least 2 colors required".into(),
            ));
        }

        // Validate: all intensities in 0.0-1.0 range
        for &(intensity, _) in &self.stops {
            if !(0.0..=1.0).contains(&intensity) {
                return Err(DotmaxError::InvalidIntensity(intensity));
            }
        }

        // Sort by intensity ascending
        self.stops
            .sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));

        // Validate: no duplicate intensity values
        for window in self.stops.windows(2) {
            if (window[0].0 - window[1].0).abs() < f32::EPSILON {
                return Err(DotmaxError::InvalidColorScheme(
                    "duplicate intensity value".into(),
                ));
            }
        }

        // Extract colors in sorted order
        let colors: Vec<Color> = self.stops.into_iter().map(|(_, color)| color).collect();

        // Create the ColorScheme
        // Note: ColorScheme::new validates non-empty, which we've already ensured
        ColorScheme::new(self.name, colors)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // ========================================================================
    // AC1: ColorSchemeBuilder Struct Tests
    // ========================================================================

    #[test]
    fn test_builder_new_creates_empty_builder() {
        let builder = ColorSchemeBuilder::new("test");
        assert_eq!(builder.name, "test");
        assert!(builder.stops.is_empty());
    }

    #[test]
    fn test_builder_new_accepts_string() {
        let builder = ColorSchemeBuilder::new(String::from("owned_string"));
        assert_eq!(builder.name, "owned_string");
    }

    #[test]
    fn test_builder_debug_trait() {
        let builder = ColorSchemeBuilder::new("debug_test");
        let debug_str = format!("{:?}", builder);
        assert!(debug_str.contains("ColorSchemeBuilder"));
        assert!(debug_str.contains("debug_test"));
    }

    #[test]
    fn test_builder_clone_trait() {
        let builder = ColorSchemeBuilder::new("clone_test")
            .add_color(0.0, Color::black())
            .add_color(1.0, Color::white());
        let cloned = builder.clone();
        assert_eq!(cloned.name, "clone_test");
        assert_eq!(cloned.stops.len(), 2);
    }

    // ========================================================================
    // AC2: Intensity-Based Color Stops Tests
    // ========================================================================

    #[test]
    fn test_add_color_stores_intensity_and_color() {
        let builder = ColorSchemeBuilder::new("test").add_color(0.5, Color::rgb(255, 0, 0));
        assert_eq!(builder.stops.len(), 1);
        assert_eq!(builder.stops[0].0, 0.5);
        assert_eq!(builder.stops[0].1, Color::rgb(255, 0, 0));
    }

    #[test]
    fn test_add_color_method_chaining() {
        let builder = ColorSchemeBuilder::new("test")
            .add_color(0.0, Color::black())
            .add_color(0.5, Color::rgb(128, 128, 128))
            .add_color(1.0, Color::white());
        assert_eq!(builder.stops.len(), 3);
    }

    #[test]
    fn test_add_color_multiple_stops() {
        let builder = ColorSchemeBuilder::new("multi")
            .add_color(0.0, Color::black())
            .add_color(0.25, Color::rgb(64, 64, 64))
            .add_color(0.5, Color::rgb(128, 128, 128))
            .add_color(0.75, Color::rgb(192, 192, 192))
            .add_color(1.0, Color::white());
        assert_eq!(builder.stops.len(), 5);
    }

    // ========================================================================
    // AC3: Validation Rules Tests
    // ========================================================================

    #[test]
    fn test_build_validates_empty_stops() {
        let result = ColorSchemeBuilder::new("empty").build();
        assert!(matches!(result, Err(DotmaxError::InvalidColorScheme(_))));
        if let Err(DotmaxError::InvalidColorScheme(msg)) = result {
            assert!(msg.contains("at least 2 colors"));
        }
    }

    #[test]
    fn test_build_validates_single_stop() {
        let result = ColorSchemeBuilder::new("single")
            .add_color(0.5, Color::white())
            .build();
        assert!(matches!(result, Err(DotmaxError::InvalidColorScheme(_))));
    }

    #[test]
    fn test_build_validates_intensity_negative() {
        let result = ColorSchemeBuilder::new("negative")
            .add_color(-0.5, Color::black())
            .add_color(1.0, Color::white())
            .build();
        assert!(matches!(result, Err(DotmaxError::InvalidIntensity(_))));
        if let Err(DotmaxError::InvalidIntensity(val)) = result {
            assert!(val < 0.0);
        }
    }

    #[test]
    fn test_build_validates_intensity_above_one() {
        let result = ColorSchemeBuilder::new("above_one")
            .add_color(0.0, Color::black())
            .add_color(1.5, Color::white())
            .build();
        assert!(matches!(result, Err(DotmaxError::InvalidIntensity(_))));
        if let Err(DotmaxError::InvalidIntensity(val)) = result {
            assert!(val > 1.0);
        }
    }

    #[test]
    fn test_build_validates_duplicate_intensity() {
        let result = ColorSchemeBuilder::new("duplicate")
            .add_color(0.5, Color::black())
            .add_color(0.5, Color::white())
            .build();
        assert!(matches!(result, Err(DotmaxError::InvalidColorScheme(_))));
        if let Err(DotmaxError::InvalidColorScheme(msg)) = result {
            assert!(msg.contains("duplicate"));
        }
    }

    #[test]
    fn test_build_with_valid_stops_two_colors() {
        let result = ColorSchemeBuilder::new("two")
            .add_color(0.0, Color::black())
            .add_color(1.0, Color::white())
            .build();
        assert!(result.is_ok());
        let scheme = result.unwrap();
        assert_eq!(scheme.name(), "two");
        assert_eq!(scheme.colors().len(), 2);
    }

    #[test]
    fn test_build_with_valid_stops_three_colors() {
        let result = ColorSchemeBuilder::new("three")
            .add_color(0.0, Color::black())
            .add_color(0.5, Color::rgb(128, 128, 128))
            .add_color(1.0, Color::white())
            .build();
        assert!(result.is_ok());
        assert_eq!(result.unwrap().colors().len(), 3);
    }

    #[test]
    fn test_build_with_valid_stops_five_colors() {
        let result = ColorSchemeBuilder::new("five")
            .add_color(0.0, Color::rgb(0, 0, 0))
            .add_color(0.25, Color::rgb(64, 0, 0))
            .add_color(0.5, Color::rgb(128, 0, 0))
            .add_color(0.75, Color::rgb(192, 0, 0))
            .add_color(1.0, Color::rgb(255, 0, 0))
            .build();
        assert!(result.is_ok());
        assert_eq!(result.unwrap().colors().len(), 5);
    }

    #[test]
    fn test_build_with_valid_stops_ten_colors() {
        let mut builder = ColorSchemeBuilder::new("ten");
        for i in 0..10 {
            let intensity = i as f32 / 9.0;
            let gray = (i * 28) as u8;
            builder = builder.add_color(intensity, Color::rgb(gray, gray, gray));
        }
        let result = builder.build();
        assert!(result.is_ok());
        assert_eq!(result.unwrap().colors().len(), 10);
    }

    // ========================================================================
    // AC4: Automatic Intensity Sorting Tests
    // ========================================================================

    #[test]
    fn test_build_sorts_stops_by_intensity() {
        // Add colors out of order
        let scheme = ColorSchemeBuilder::new("shuffled")
            .add_color(1.0, Color::white())
            .add_color(0.0, Color::black())
            .add_color(0.5, Color::rgb(128, 128, 128))
            .build()
            .unwrap();

        // Colors should be sorted: black, gray, white
        let colors = scheme.colors();
        assert_eq!(colors[0], Color::black());
        assert_eq!(colors[1], Color::rgb(128, 128, 128));
        assert_eq!(colors[2], Color::white());
    }

    #[test]
    fn test_build_sorts_complex_shuffled_order() {
        let scheme = ColorSchemeBuilder::new("complex")
            .add_color(0.75, Color::rgb(192, 192, 192))
            .add_color(0.25, Color::rgb(64, 64, 64))
            .add_color(1.0, Color::white())
            .add_color(0.0, Color::black())
            .add_color(0.5, Color::rgb(128, 128, 128))
            .build()
            .unwrap();

        let colors = scheme.colors();
        assert_eq!(colors.len(), 5);
        assert_eq!(colors[0], Color::black()); // 0.0
        assert_eq!(colors[1], Color::rgb(64, 64, 64)); // 0.25
        assert_eq!(colors[2], Color::rgb(128, 128, 128)); // 0.5
        assert_eq!(colors[3], Color::rgb(192, 192, 192)); // 0.75
        assert_eq!(colors[4], Color::white()); // 1.0
    }

    #[test]
    fn test_build_sorting_does_not_affect_interpolation() {
        // Build scheme with colors in random order
        let scheme = ColorSchemeBuilder::new("interp_test")
            .add_color(1.0, Color::rgb(255, 255, 255))
            .add_color(0.0, Color::rgb(0, 0, 0))
            .build()
            .unwrap();

        // Interpolation should work correctly
        let black = scheme.sample(0.0);
        let white = scheme.sample(1.0);
        let gray = scheme.sample(0.5);

        assert_eq!(black.r, 0);
        assert_eq!(white.r, 255);
        assert!(gray.r >= 127 && gray.r <= 128);
    }

    // ========================================================================
    // AC5: Integration with sample() Tests
    // ========================================================================

    #[test]
    fn test_built_scheme_sample_at_boundaries() {
        let scheme = ColorSchemeBuilder::new("boundary")
            .add_color(0.0, Color::rgb(0, 0, 0))
            .add_color(1.0, Color::rgb(255, 255, 255))
            .build()
            .unwrap();

        let black = scheme.sample(0.0);
        let white = scheme.sample(1.0);

        assert_eq!(black, Color::rgb(0, 0, 0));
        assert_eq!(white, Color::rgb(255, 255, 255));
    }

    #[test]
    fn test_built_scheme_sample_midpoint() {
        let scheme = ColorSchemeBuilder::new("midpoint")
            .add_color(0.0, Color::rgb(0, 0, 0))
            .add_color(1.0, Color::rgb(255, 255, 255))
            .build()
            .unwrap();

        let mid = scheme.sample(0.5);
        // Should be approximately 128 (gray)
        assert!(mid.r >= 127 && mid.r <= 128);
        assert!(mid.g >= 127 && mid.g <= 128);
        assert!(mid.b >= 127 && mid.b <= 128);
    }

    #[test]
    fn test_built_scheme_sample_at_color_stops() {
        let scheme = ColorSchemeBuilder::new("stops")
            .add_color(0.0, Color::rgb(255, 0, 0)) // Red
            .add_color(0.5, Color::rgb(0, 255, 0)) // Green
            .add_color(1.0, Color::rgb(0, 0, 255)) // Blue
            .build()
            .unwrap();

        let red = scheme.sample(0.0);
        let green = scheme.sample(0.5);
        let blue = scheme.sample(1.0);

        assert_eq!(red, Color::rgb(255, 0, 0));
        assert_eq!(green, Color::rgb(0, 255, 0));
        assert_eq!(blue, Color::rgb(0, 0, 255));
    }

    #[test]
    fn test_built_scheme_sample_between_stops() {
        let scheme = ColorSchemeBuilder::new("between")
            .add_color(0.0, Color::rgb(255, 0, 0)) // Red
            .add_color(1.0, Color::rgb(0, 0, 255)) // Blue
            .build()
            .unwrap();

        let mid = scheme.sample(0.5);
        // Should be purple-ish (mix of red and blue)
        assert!(mid.r > 100 && mid.r < 150); // ~128
        assert!(mid.b > 100 && mid.b < 150); // ~128
        assert_eq!(mid.g, 0); // Green should stay 0
    }

    #[test]
    fn test_built_scheme_sample_clamps_intensity() {
        let scheme = ColorSchemeBuilder::new("clamp")
            .add_color(0.0, Color::black())
            .add_color(1.0, Color::white())
            .build()
            .unwrap();

        // Clamped to 0.0
        let below = scheme.sample(-0.5);
        assert_eq!(below, Color::black());

        // Clamped to 1.0
        let above = scheme.sample(1.5);
        assert_eq!(above, Color::white());
    }

    // ========================================================================
    // AC7: Comprehensive Builder Workflow Test
    // ========================================================================

    #[test]
    fn test_comprehensive_builder_workflow() {
        // Create a custom "sunset" gradient
        let scheme = ColorSchemeBuilder::new("sunset")
            .add_color(0.0, Color::rgb(25, 25, 112)) // Dark blue
            .add_color(0.3, Color::rgb(255, 69, 0)) // Red-orange
            .add_color(0.5, Color::rgb(255, 140, 0)) // Orange
            .add_color(0.7, Color::rgb(255, 215, 0)) // Gold
            .add_color(1.0, Color::rgb(255, 255, 224)) // Light yellow
            .build()
            .unwrap();

        // Verify scheme metadata
        assert_eq!(scheme.name(), "sunset");
        assert_eq!(scheme.colors().len(), 5);

        // Verify sampling at various points
        let dawn = scheme.sample(0.0);
        assert_eq!(dawn, Color::rgb(25, 25, 112));

        let dusk = scheme.sample(1.0);
        assert_eq!(dusk, Color::rgb(255, 255, 224));

        // Mid-range should be interpolated
        let mid = scheme.sample(0.5);
        assert_eq!(mid, Color::rgb(255, 140, 0)); // Exact stop

        // Between stops
        let between = scheme.sample(0.15);
        assert!(between.r > 100); // Interpolating toward orange
    }

    // ========================================================================
    // Edge Case Tests
    // ========================================================================

    #[test]
    fn test_intensity_at_exact_boundaries() {
        let result = ColorSchemeBuilder::new("exact")
            .add_color(0.0, Color::black())
            .add_color(1.0, Color::white())
            .build();
        assert!(result.is_ok());
    }

    #[test]
    fn test_very_close_intensities_but_not_duplicate() {
        let result = ColorSchemeBuilder::new("close")
            .add_color(0.0, Color::black())
            .add_color(0.001, Color::rgb(1, 1, 1))
            .add_color(1.0, Color::white())
            .build();
        assert!(result.is_ok());
    }

    #[test]
    fn test_name_with_special_characters() {
        let result = ColorSchemeBuilder::new("my-scheme_v2.0")
            .add_color(0.0, Color::black())
            .add_color(1.0, Color::white())
            .build();
        assert!(result.is_ok());
        assert_eq!(result.unwrap().name(), "my-scheme_v2.0");
    }

    #[test]
    fn test_name_with_unicode() {
        let result = ColorSchemeBuilder::new("日本語の名前")
            .add_color(0.0, Color::black())
            .add_color(1.0, Color::white())
            .build();
        assert!(result.is_ok());
        assert_eq!(result.unwrap().name(), "日本語の名前");
    }

    #[test]
    fn test_empty_name() {
        let result = ColorSchemeBuilder::new("")
            .add_color(0.0, Color::black())
            .add_color(1.0, Color::white())
            .build();
        assert!(result.is_ok());
        assert_eq!(result.unwrap().name(), "");
    }
}