charton 0.5.0

A high-performance, layered charting system for Rust, featuring a flexible data core and multi-backend rendering.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

use crate::core::data::AggregateOp;
use crate::scale::{Expansion, ResolvedScale, Scale, ScaleDomain};

/// Represents a color encoding specification for chart elements.
///
/// The `Color` struct defines how data values are mapped to visual colors.
/// It supports both continuous mappings (gradients) and discrete mappings (palettes).
///
/// ### Architecture Note:
/// Following the "Intent vs. Resolution" pattern, this struct holds user configuration
/// until the `LayeredChart` resolves the final scale. This is where your specific
/// orange-ish color gradient will be stored:
/// `(0.000, 1.000, 0.961, 0.922), // #fff5eb ...`
#[derive(Debug, Clone)]
pub struct Color {
    // --- User Configuration (Intent/Inputs) ---
    /// The name of the data column used for color encoding.
    pub(crate) field: String,

    /// Statistical operation to apply to the data (e.g., Sum, Mean).
    /// Defaults to `AggregateOp::Sum`.
    pub(crate) aggregate: AggregateOp,

    /// The desired scale transformation (e.g., Linear, Discrete, Log).
    pub(crate) scale_type: Option<Scale>,

    /// An explicit data domain for color mapping.
    pub(crate) domain: Option<ScaleDomain>,

    /// Rules for adding padding or buffer to the ends of the color scale domain.
    pub(crate) expansion: Option<Expansion>,

    // --- System Resolution (Result/Outputs) ---
    /// Stores the resolved scale instance. Using RwLock to support
    /// back-filling updates across multiple render calls.
    pub(crate) resolved_scale: ResolvedScale,
}

impl Color {
    /// Creates a new Color encoding for the specified data field.
    pub fn new(field: &str) -> Self {
        Self {
            field: field.to_string(),
            aggregate: AggregateOp::default(), // Defaults to Sum
            scale_type: None,
            domain: None,
            expansion: None,
            resolved_scale: ResolvedScale::none(),
        }
    }

    pub fn with_aggregate<A: Into<AggregateOp>>(mut self, op: A) -> Self {
        self.aggregate = op.into();
        self
    }

    /// Explicitly sets the scale type for color mapping (e.g., Linear, Log).
    pub fn with_scale(mut self, scale_type: Scale) -> Self {
        self.scale_type = Some(scale_type);
        self
    }

    /// Sets an explicit domain (limits) for the color scale.
    pub fn with_domain(mut self, domain: ScaleDomain) -> Self {
        self.domain = Some(domain);
        self
    }

    /// Configures the expansion padding for the color scale.
    pub fn with_expandsion(mut self, expansion: Expansion) -> Self {
        self.expansion = Some(expansion);
        self
    }
}

/// Convenience builder function to create a new Color encoding.
///
pub fn color(field: &str) -> Color {
    Color::new(field)
}