Skip to main content

gradient_bar/
gradient.rs

1use std::fmt::Write as _;
2
3/// A curated set of smooth, true-color progress gradients.
4///
5/// Each variant interpolates a *linear* ramp between a start and an end RGB
6/// color across the bar, giving a gradual multi-stop feel rather than the flat
7/// two-tone `wide_bar`. Works on any terminal with 24-bit color support (the
8/// default on modern terminals); degraded gracefully elsewhere.
9#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
10pub enum Gradient {
11    /// Deep blue -> ice cyan. The Enkryptit signature look.
12    Ocean,
13    /// Violet -> magenta.
14    Violet,
15    /// Warm orange -> gold.
16    Sunset,
17    /// Aqua green -> mint.
18    Mint,
19    /// Amber -> rose (danger / critical ops).
20    Ember,
21    /// Cool white -> pale blue.
22    Ice,
23}
24
25impl Gradient {
26    /// The `(start, end)` RGB stops for this gradient.
27    fn stops(self) -> ((u8, u8, u8), (u8, u8, u8)) {
28        match self {
29            Gradient::Ocean => ((8, 150, 255), (150, 235, 255)),
30            Gradient::Violet => ((140, 60, 255), (255, 90, 220)),
31            Gradient::Sunset => ((255, 120, 60), (255, 220, 90)),
32            Gradient::Mint => ((40, 200, 150), (150, 245, 190)),
33            Gradient::Ember => ((255, 150, 50), (255, 60, 100)),
34            Gradient::Ice => ((150, 200, 255), (245, 250, 255)),
35        }
36    }
37
38    /// Render a `width`-column true-color gradient bar reflecting `fraction`
39    /// (0.0 → 1.0) of completed work.
40    pub fn render(self, fraction: f32, width: usize) -> String {
41        let ((r0, g0, b0), (r1, g1, b1)) = self.stops();
42        let filled = (fraction.clamp(0.0, 1.0) * width as f32).round() as usize;
43
44        let mut out = String::with_capacity(width * 16 + 8);
45
46        for i in 0..filled {
47            let t = if width > 1 {
48                i as f32 / (width - 1) as f32
49            } else {
50                0.0
51            };
52            let r = r0 as f32 + (r1 as f32 - r0 as f32) * t;
53            let g = g0 as f32 + (g1 as f32 - g0 as f32) * t;
54            let b = b0 as f32 + (b1 as f32 - b0 as f32) * t;
55            let _ = write!(out, "\x1b[38;2;{};{};{}m█", r as u8, g as u8, b as u8);
56        }
57
58        if filled < width {
59            let _ = write!(out, "\x1b[38;2;58;66;82m"); // dim slate for the remainder
60            for _ in filled..width {
61                out.push('·');
62            }
63        }
64
65        out.push_str("\x1b[0m");
66        out
67    }
68
69    /// name for the gradient (used in `Debug`/messages).
70    pub fn name(self) -> &'static str {
71        match self {
72            Gradient::Ocean => "Ocean",
73            Gradient::Violet => "Violet",
74            Gradient::Sunset => "Sunset",
75            Gradient::Mint => "Mint",
76            Gradient::Ember => "Ember",
77            Gradient::Ice => "Ice",
78        }
79    }
80}
81
82#[cfg(test)]
83mod tests {
84    use super::*;
85
86    #[test]
87    fn name_returns_correct_strings() {
88        assert_eq!(Gradient::Ocean.name(), "Ocean");
89        assert_eq!(Gradient::Violet.name(), "Violet");
90        assert_eq!(Gradient::Sunset.name(), "Sunset");
91        assert_eq!(Gradient::Mint.name(), "Mint");
92        assert_eq!(Gradient::Ember.name(), "Ember");
93        assert_eq!(Gradient::Ice.name(), "Ice");
94    }
95
96    #[test]
97    fn stops_are_distinct_per_gradient() {
98        let seen: Vec<_> = [
99            Gradient::Ocean,
100            Gradient::Violet,
101            Gradient::Sunset,
102            Gradient::Mint,
103            Gradient::Ember,
104            Gradient::Ice,
105        ]
106        .iter()
107        .map(|g| g.stops())
108        .collect();
109        for (i, a) in seen.iter().enumerate() {
110            for (j, b) in seen.iter().enumerate() {
111                if i != j {
112                    assert_ne!(a, b, "gradients {i} and {j} should have different stops");
113                }
114            }
115        }
116    }
117
118    #[test]
119    fn render_at_zero_is_all_dots() {
120        let out = Gradient::Ocean.render(0.0, 20);
121        assert!(out.contains("·"), "expected dots at 0%: {out}");
122        assert!(
123            !out.contains("█"),
124            "should have no filled blocks at 0%: {out}"
125        );
126    }
127
128    #[test]
129    fn render_at_one_is_all_filled() {
130        let out = Gradient::Ocean.render(1.0, 20);
131        assert!(out.contains("█"), "expected filled blocks at 100%: {out}");
132        let dot_count = out.matches('·').count();
133        assert_eq!(dot_count, 0, "should have no dots at 100%: {out}");
134    }
135
136    #[test]
137    fn render_halfway_approximately_half() {
138        let width = 20;
139        let out = Gradient::Sunset.render(0.5, width);
140        let filled = out.matches('█').count();
141        let dots = out.matches('·').count();
142        assert_eq!(filled + dots, width, "total chars should equal width");
143        assert!(
144            (filled as i32 - dots as i32).unsigned_abs() <= 2,
145            "filled ({filled}) and dots ({dots}) should be roughly equal"
146        );
147    }
148
149    #[test]
150    fn render_width_one() {
151        let out_zero = Gradient::Violet.render(0.0, 1);
152        assert!(out_zero.contains('·'));
153
154        let out_one = Gradient::Violet.render(1.0, 1);
155        assert!(out_one.contains('█'));
156    }
157
158    #[test]
159    fn render_clamps_above_one() {
160        let out = Gradient::Mint.render(1.5, 10);
161        let filled = out.matches('█').count();
162        assert_eq!(filled, 10, "fraction > 1.0 should clamp to full bar");
163    }
164
165    #[test]
166    fn render_clamps_below_zero() {
167        let out = Gradient::Ember.render(-0.5, 10);
168        let filled = out.matches('█').count();
169        assert_eq!(filled, 0, "fraction < 0.0 should clamp to empty bar");
170    }
171
172    #[test]
173    fn render_contains_ansi_reset() {
174        let out = Gradient::Ice.render(0.5, 10);
175        assert!(
176            out.ends_with("\x1b[0m"),
177            "output should end with ANSI reset"
178        );
179    }
180
181    #[test]
182    fn render_each_variant_does_not_panic() {
183        for grad in [
184            Gradient::Ocean,
185            Gradient::Violet,
186            Gradient::Sunset,
187            Gradient::Mint,
188            Gradient::Ember,
189            Gradient::Ice,
190        ] {
191            grad.render(0.0, 0);
192            grad.render(0.33, 30);
193            grad.render(1.0, 1);
194        }
195    }
196}