Skip to main content

comb/draw/
effects.rs

1//! Reusable visual effects. Each takes an animation `phase` (a monotonically
2//! rising frame counter) so callers stay in control of timing.
3
4use crate::core::style::{Color, Modifier, Style};
5use crate::core::text::Span;
6
7/// A grayscale "shimmer": a bright highlight sweeps left-to-right across `text`,
8/// so a word glows while something is in flight. `phase` is the frame counter.
9pub fn shimmer(text: &str, phase: usize) -> Vec<Span> {
10    let chars: Vec<char> = text.chars().collect();
11    let n = chars.len() as i32;
12    if n == 0 {
13        return Vec::new();
14    }
15    // The highlight head sweeps from just before the word to just past it.
16    let head = (phase as i32 % (n + 6)) - 3;
17    let (lo, hi) = (0x70i32, 0xf2i32);
18    chars
19        .into_iter()
20        .enumerate()
21        .map(|(i, c)| {
22            let dist = (i as i32 - head).unsigned_abs() as f32;
23            let t = (1.0 - dist / 3.0).max(0.0);
24            let v = (lo as f32 + (hi - lo) as f32 * t) as u8;
25            Span::styled(
26                c.to_string(),
27                Style::new().fg(Color::rgb(v, v, v)).add(Modifier::BOLD),
28            )
29        })
30        .collect()
31}
32
33/// A pulsing intensity in `[lo, hi]` following a triangle wave of `period`
34/// frames — good for a breathing cursor or a soft attention cue.
35pub fn pulse(phase: usize, period: usize, lo: u8, hi: u8) -> Color {
36    let period = period.max(2);
37    let p = phase % period;
38    let half = period / 2;
39    let t = if p < half {
40        p as f32 / half as f32
41    } else {
42        1.0 - (p - half) as f32 / (period - half) as f32
43    };
44    let v = lo as f32 + (hi as f32 - lo as f32) * t;
45    let v = v as u8;
46    Color::rgb(v, v, v)
47}
48
49/// A named spinner: a cyclic set of single-width frames. Advance with `phase`.
50pub struct Spinner {
51    pub name: &'static str,
52    pub frames: &'static [&'static str],
53}
54
55impl Spinner {
56    pub fn frame(&self, phase: usize) -> &'static str {
57        if self.frames.is_empty() {
58            " "
59        } else {
60            self.frames[phase % self.frames.len()]
61        }
62    }
63}
64
65/// A gallery of ready-made spinners — every frame is one cell wide, no emoji, so
66/// they line up perfectly in the grid.
67pub const SPINNERS: &[Spinner] = &[
68    Spinner {
69        name: "braille",
70        frames: &["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"],
71    },
72    Spinner {
73        name: "dots",
74        frames: &["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"],
75    },
76    Spinner {
77        name: "line",
78        frames: &["|", "/", "-", "\\"],
79    },
80    Spinner {
81        name: "arc",
82        frames: &["◜", "◠", "◝", "◞", "◡", "◟"],
83    },
84    Spinner {
85        name: "circle",
86        frames: &["◐", "◓", "◑", "◒"],
87    },
88    Spinner {
89        name: "triangle",
90        frames: &["◢", "◣", "◤", "◥"],
91    },
92    Spinner {
93        name: "quadrant",
94        frames: &["▖", "▘", "▝", "▗"],
95    },
96    Spinner {
97        name: "bar",
98        frames: &[
99            "▏", "▎", "▍", "▌", "▋", "▊", "▉", "█", "▉", "▊", "▌", "▍", "▎",
100        ],
101    },
102    Spinner {
103        name: "star",
104        frames: &["✶", "✸", "✹", "✺", "✹", "✷"],
105    },
106    Spinner {
107        name: "bounce",
108        frames: &["⠁", "⠂", "⠄", "⠂"],
109    },
110];
111
112/// Render a fractional progress bar of `width` cells using eighth-block glyphs
113/// for a smooth sub-cell edge. Returns styled spans (filled run + empty run).
114pub fn bar(fraction: f32, width: usize, filled: Style, empty: Style) -> Vec<Span> {
115    let frac = fraction.clamp(0.0, 1.0);
116    let total = width as f32 * frac;
117    let full = (total.floor() as usize).min(width);
118    let eighths = ["", "▏", "▎", "▍", "▌", "▋", "▊", "▉"];
119
120    let mut s = "█".repeat(full);
121    let mut used = full;
122    if used < width {
123        let idx = ((total - full as f32) * 8.0).round() as usize;
124        if idx > 0 {
125            s.push_str(eighths[idx.min(7)]);
126            used += 1;
127        }
128    }
129
130    let mut out = Vec::new();
131    if !s.is_empty() {
132        out.push(Span::styled(s, filled));
133    }
134    if used < width {
135        out.push(Span::styled(" ".repeat(width - used), empty));
136    }
137    out
138}
139
140const SPARK: [char; 8] = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
141
142/// A tiny inline sparkline: `values` in `[0, 1]`, resampled to `width` cells.
143pub fn sparkline(values: &[f32], width: usize, style: Style) -> Vec<Span> {
144    if width == 0 {
145        return Vec::new();
146    }
147    if values.is_empty() {
148        return vec![Span::styled(" ".repeat(width), style)];
149    }
150    let n = values.len();
151    let mut s = String::with_capacity(width);
152    for i in 0..width {
153        let idx = i * n / width;
154        let v = values[idx.min(n - 1)].clamp(0.0, 1.0);
155        let ch = SPARK[(v * 7.0).round() as usize];
156        s.push(ch);
157    }
158    vec![Span::styled(s, style)]
159}