ttui 2.0.0

A terminal UI framework built from first principles: direct control over text rendering, color, pane layout, and multiplexing.
Documentation
//! Linear/eased interpolation and progress helpers — the building
//! blocks every `Transition`-driven animation in this codebase uses.

use crossterm::style::Color;
use std::time::Duration;

/// Linear interpolation from `start` to `end`, `t` clamped to `0..1`.
pub fn lerp(start: f32, end: f32, t: f32) -> f32 {
    let t = t.clamp(0.0, 1.0);
    start + (end - start) * t
}

/// Interpolation from `start` to `end` that starts fast and eases
/// into `end`, `t` clamped to `0..1`.
pub fn ease_out(start: f32, end: f32, t: f32) -> f32 {
    let t = t.clamp(0.0, 1.0);
    let eased = 1.0 - (1.0 - t) * (1.0 - t);
    lerp(start, end, eased)
}

/// `elapsed / duration`, clamped to `0..1`; a zero `duration` is
/// always complete.
pub fn progress(elapsed: Duration, duration: Duration) -> f32 {
    if duration.is_zero() {
        return 1.0;
    }
    (elapsed.as_secs_f32() / duration.as_secs_f32()).clamp(0.0, 1.0)
}

/// Color lerp from `from` to `to`, `t` clamped to `0..1`.
///
/// An `Rgb` pair interpolates componentwise. Any other pair cannot —
/// `Color::Reset` means "whatever the terminal's default is" and named
/// colors are whatever the terminal's theme maps them to, so there is
/// no honest RGB value to interpolate through, and inventing one would
/// emit a shade the terminal did not choose. Such a pair therefore
/// switches at the midpoint: `from` below `0.5`, `to` at or above.
///
/// That switch is a visible step rather than a ramp, but it keeps the
/// endpoints honest, which is what actually matters — the previous
/// fallback returned `to` for every `t`, so a gradient rendered flat at
/// its end color and a fade jumped to its target on the first frame
/// (#122).
pub fn lerp_color(from: Color, to: Color, t: f32) -> Color {
    match (from, to) {
        (
            Color::Rgb {
                r: r1,
                g: g1,
                b: b1,
            },
            Color::Rgb {
                r: r2,
                g: g2,
                b: b2,
            },
        ) => Color::Rgb {
            r: lerp(r1 as f32, r2 as f32, t) as u8,
            g: lerp(g1 as f32, g2 as f32, t) as u8,
            b: lerp(b1 as f32, b2 as f32, t) as u8,
        },
        _ => {
            if t < 0.5 {
                from
            } else {
                to
            }
        }
    }
}

/// Scales an `Rgb` color's brightness by `factor`, multiplying each
/// channel: `1.0` leaves the color unchanged and `0.0` is black.
///
/// `factor` is **not clamped**. Above `1.0` the color brightens, and
/// each channel saturates at `255` rather than wrapping (Rust's
/// float-to-int cast saturates); below `0.0` it floors at black by the
/// same rule. Clamping `factor` to `0..=1` would silently turn a
/// deliberate highlight into a no-op, which is the harder bug to see.
///
/// A non-`Rgb` color passes through untouched at every factor. There is
/// nothing to scale: `Color::Reset` means "whatever the terminal's
/// default is" and a named color is whatever the terminal's theme maps
/// it to, so its brightness was never disclosed and any RGB substituted
/// for it would be fabricated.
///
/// Note this differs from `lerp_color`, deliberately: that one switches
/// non-`Rgb` colors at the midpoint (#122) because a lerp has two
/// endpoints and can honestly pick the nearer one. A scale has one
/// color and no second endpoint to fall back to, so passing it through
/// is the only non-fabricating answer.
pub fn scale_color(c: Color, factor: f32) -> Color {
    match c {
        Color::Rgb { r, g, b } => Color::Rgb {
            r: (r as f32 * factor) as u8,
            g: (g as f32 * factor) as u8,
            b: (b as f32 * factor) as u8,
        },
        other => other,
    }
}

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

    #[test]
    fn test_lerp_endpoints() {
        assert_eq!(lerp(0.0, 10.0, 0.0), 0.0);
        assert_eq!(lerp(0.0, 10.0, 1.0), 10.0);
    }

    #[test]
    fn test_lerp_midpoint() {
        assert_eq!(lerp(0.0, 10.0, 0.5), 5.0);
    }

    #[test]
    fn test_lerp_clamps_below() {
        assert_eq!(lerp(0.0, 10.0, -1.0), 0.0);
    }

    #[test]
    fn test_lerp_clamps_above() {
        assert_eq!(lerp(0.0, 10.0, 2.0), 10.0);
    }

    #[test]
    fn test_ease_out_endpoints() {
        assert_eq!(ease_out(0.0, 10.0, 0.0), 0.0);
        assert_eq!(ease_out(0.0, 10.0, 1.0), 10.0);
    }

    #[test]
    fn test_ease_out_faster_than_linear() {
        let linear = lerp(0.0, 10.0, 0.5);
        let eased = ease_out(0.0, 10.0, 0.5);
        assert!(eased > linear);
    }

    #[test]
    fn test_progress_zero_elapsed() {
        assert_eq!(progress(Duration::ZERO, Duration::from_secs(1)), 0.0);
    }

    #[test]
    fn test_progress_equal_duration() {
        assert_eq!(
            progress(Duration::from_secs(1), Duration::from_secs(1)),
            1.0
        );
    }

    #[test]
    fn test_progress_halfway() {
        assert_eq!(
            progress(Duration::from_millis(500), Duration::from_secs(1)),
            0.5
        );
    }

    #[test]
    fn test_progress_elapsed_exceeds_duration() {
        assert_eq!(
            progress(Duration::from_secs(2), Duration::from_secs(1)),
            1.0
        );
    }

    #[test]
    fn test_progress_zero_duration() {
        assert_eq!(progress(Duration::from_secs(1), Duration::ZERO), 1.0);
    }

    #[test]
    fn test_lerp_color_endpoints() {
        let from = Color::Rgb { r: 0, g: 0, b: 0 };
        let to = Color::Rgb {
            r: 200,
            g: 100,
            b: 50,
        };
        assert_eq!(lerp_color(from, to, 0.0), from);
        assert_eq!(lerp_color(from, to, 1.0), to);
    }

    #[test]
    fn test_lerp_color_midpoint() {
        let from = Color::Rgb { r: 0, g: 0, b: 0 };
        let to = Color::Rgb {
            r: 200,
            g: 100,
            b: 50,
        };
        assert_eq!(
            lerp_color(from, to, 0.5),
            Color::Rgb {
                r: 100,
                g: 50,
                b: 25
            }
        );
    }

    #[test]
    fn test_lerp_color_non_rgb_falls_back_to_target() {
        let from = Color::Reset;
        let to = Color::Rgb {
            r: 10,
            g: 20,
            b: 30,
        };
        assert_eq!(lerp_color(from, to, 0.5), to);
    }

    /// #122: the fallback used to return `to` for every `t`, so a lerp
    /// involving a non-Rgb color never showed its *source* — a gradient
    /// rendered flat at its end color, and a fade snapped to its target
    /// on the first frame. `t` is now respected at the endpoints even
    /// when the colors cannot be interpolated componentwise.
    #[test]
    fn test_lerp_color_non_rgb_endpoints_are_the_endpoints() {
        let from = Color::Green;
        let to = Color::Red;

        assert_eq!(lerp_color(from, to, 0.0), from, "t=0 must be `from`");
        assert_eq!(lerp_color(from, to, 1.0), to, "t=1 must be `to`");
        // Below the midpoint still reads as `from`, at or above as `to`.
        assert_eq!(lerp_color(from, to, 0.25), from);
        assert_eq!(lerp_color(from, to, 0.75), to);
    }

    /// A pair that *can* be interpolated is unaffected by the above.
    #[test]
    fn test_lerp_color_rgb_pair_still_interpolates_componentwise() {
        let from = Color::Rgb { r: 0, g: 0, b: 0 };
        let to = Color::Rgb {
            r: 100,
            g: 200,
            b: 40,
        };
        assert_eq!(
            lerp_color(from, to, 0.5),
            Color::Rgb {
                r: 50,
                g: 100,
                b: 20
            }
        );
    }

    #[test]
    fn scale_color_at_one_leaves_an_rgb_color_unchanged() {
        let c = Color::Rgb {
            r: 200,
            g: 100,
            b: 50,
        };
        assert_eq!(scale_color(c, 1.0), c);
    }

    #[test]
    fn scale_color_at_zero_is_black() {
        let c = Color::Rgb {
            r: 200,
            g: 100,
            b: 50,
        };
        assert_eq!(scale_color(c, 0.0), Color::Rgb { r: 0, g: 0, b: 0 });
    }

    #[test]
    fn scale_color_at_half_halves_each_channel() {
        let c = Color::Rgb {
            r: 200,
            g: 100,
            b: 50,
        };
        assert_eq!(
            scale_color(c, 0.5),
            Color::Rgb {
                r: 100,
                g: 50,
                b: 25
            }
        );
    }

    #[test]
    fn scale_color_passes_non_rgb_through_at_every_factor() {
        for factor in [0.0, 0.5, 1.0, 2.0, -1.0] {
            assert_eq!(scale_color(Color::Reset, factor), Color::Reset);
            assert_eq!(scale_color(Color::Green, factor), Color::Green);
        }
    }

    /// `factor` is deliberately not clamped: a factor above `1.0`
    /// brightens, and each channel saturates at `255` rather than
    /// wrapping. Asserted rather than assumed, because the whole
    /// behaviour rests on Rust's saturating float-to-int cast.
    #[test]
    fn scale_color_above_one_brightens_and_saturates_at_255() {
        let c = Color::Rgb {
            r: 200,
            g: 100,
            b: 50,
        };
        assert_eq!(
            scale_color(c, 2.0),
            Color::Rgb {
                r: 255,
                g: 200,
                b: 100
            }
        );
    }

    /// The same saturating cast at the other end: a negative factor
    /// floors at `0` rather than wrapping to a bright channel.
    #[test]
    fn scale_color_below_zero_saturates_to_black() {
        let c = Color::Rgb {
            r: 200,
            g: 100,
            b: 50,
        };
        assert_eq!(scale_color(c, -1.0), Color::Rgb { r: 0, g: 0, b: 0 });
    }
}