slt/context/widgets_display/

gauge.rs

// Gauge / line_gauge widgets — block-fill and single-line progress indicators
// with optional inline labels.
//
// Introduced in v0.20.0 (#224). Complements the unlabeled
// `Context::progress_bar` / `Context::progress` (`textarea_progress.rs`).
//
// Callers use a chainable builder pattern
// (`ui.gauge(0.5).label("CPU").width(48)`). Auto-renders on `Drop`; call
// `.show()` to get a [`GaugeResponse`] back. Ratios are `f64` to match
// `animate_value`, chart APIs, and `progress_bar` — no more `f32` outliers.

use super::*;

/// Default width for `gauge` and `line_gauge` when no explicit width is set.
const DEFAULT_GAUGE_WIDTH: u32 = 20;

impl Context {
    /// Begin building a block-fill progress bar with optional centered label.
    ///
    /// `ratio` is clamped to `0.0..=1.0`. The returned [`Gauge`] auto-renders
    /// when dropped, so a bare `ui.gauge(0.5);` produces a default-width bar.
    /// Chain `.label(...)`, `.width(...)`, or `.color(...)` to customize.
    /// Call `.show()` (instead of dropping) to capture a [`GaugeResponse`].
    ///
    /// Color tiers follow theme colors: `success` below 50%, `warning` 50–80%,
    /// `error` at or above 80%. Override per-call with `.color(...)`.
    ///
    /// # Example
    ///
    /// ```no_run
    /// # slt::run(|ui: &mut slt::Context| {
    /// ui.gauge(0.6).label("60%");
    /// let r = ui.gauge(0.42).label("CPU").width(48).show();
    /// if r.hovered { /* attach tooltip */ }
    /// # });
    /// ```
    ///
    /// # Family
    ///
    /// The gauge family covers ratio-based progress indicators:
    ///
    /// - [`gauge`](Self::gauge) — block-fill bar with a centered label (this method).
    /// - [`line_gauge`](Self::line_gauge) — single-line bar with a trailing label
    ///   and configurable fill/empty chars.
    /// - [`progress_bar`](Self::progress_bar) / [`progress`](Self::progress) —
    ///   unlabeled progress bars.
    pub fn gauge(&mut self, ratio: f64) -> Gauge<'_> {
        Gauge::new(self, ratio)
    }

    /// Begin building a single-line gauge with configurable fill/empty chars.
    ///
    /// `ratio` is clamped to `0.0..=1.0`. Chain `.label(...)`, `.width(...)`,
    /// `.filled(...)`, `.empty(...)` to customize. Auto-renders on `Drop`;
    /// call `.show()` to capture a [`GaugeResponse`].
    ///
    /// # Example
    ///
    /// ```no_run
    /// # slt::run(|ui: &mut slt::Context| {
    /// ui.line_gauge(0.6).label("60%").width(24);
    /// ui.line_gauge(0.78).label("Memory").width(48).filled('━');
    /// # });
    /// ```
    ///
    /// # Family
    ///
    /// The gauge family covers ratio-based progress indicators:
    ///
    /// - [`line_gauge`](Self::line_gauge) — single-line bar with a trailing
    ///   label (this method).
    /// - [`gauge`](Self::gauge) — block-fill bar with a centered label.
    /// - [`progress_bar`](Self::progress_bar) / [`progress`](Self::progress) —
    ///   unlabeled progress bars.
    pub fn line_gauge(&mut self, ratio: f64) -> LineGauge<'_> {
        LineGauge::new(self, ratio)
    }
}

/// Block-fill gauge builder. Auto-renders on `Drop`.
///
/// Constructed via [`Context::gauge`]. Chainable `.label`, `.width`, `.color`
/// methods configure the gauge before it renders. Drop the value to render
/// without capturing a response, or call [`Self::show`] to render and obtain
/// a [`GaugeResponse`].
///
/// `Drop` is intentional: `ui.gauge(0.5).label("CPU");` is the idiomatic form
/// when the response isn't needed, mirroring egui's `ui.add(...)`. Use
/// [`Self::show`] when you need the response.
///
/// # Family
///
/// Use [`LineGauge`] for a compact single-line bar with a trailing label, or
/// [`Context::progress_bar`] / [`Context::progress`] for an unlabeled bar.
pub struct Gauge<'a> {
    ctx: Option<&'a mut Context>,
    ratio: f64,
    label: Option<String>,
    width: Option<u32>,
    color: Option<Color>,
}

impl<'a> Gauge<'a> {
    fn new(ctx: &'a mut Context, ratio: f64) -> Self {
        Self {
            ctx: Some(ctx),
            ratio,
            label: None,
            width: None,
            color: None,
        }
    }

    /// Set the centered inline label. Empty string is treated as "no label".
    ///
    /// Accepts both `&str` and owned `String` via `impl Into<String>` so
    /// callers with already-owned strings (e.g. `format!(...)`) don't pay a
    /// redundant clone.
    pub fn label(mut self, label: impl Into<String>) -> Self {
        let label = label.into();
        if label.is_empty() {
            self.label = None;
        } else {
            self.label = Some(label);
        }
        self
    }

    /// Set the bar width in terminal cells (default: 20).
    pub fn width(mut self, w: u32) -> Self {
        self.width = Some(w);
        self
    }

    /// Override the auto-tiered color with a fixed color.
    pub fn color(mut self, c: Color) -> Self {
        self.color = Some(c);
        self
    }

    /// Render now and return the [`GaugeResponse`].
    pub fn show(mut self) -> GaugeResponse {
        let Some(ctx) = self.ctx.take() else {
            // `show` consumes the builder, so safe code cannot reach this
            // branch. Stay defensive if the internal invariant changes.
            return GaugeResponse::default();
        };
        render_gauge(
            ctx,
            self.ratio,
            self.width.unwrap_or(DEFAULT_GAUGE_WIDTH),
            self.label.as_deref().unwrap_or(""),
            self.color,
        )
    }
}

impl Drop for Gauge<'_> {
    fn drop(&mut self) {
        if let Some(ctx) = self.ctx.take() {
            let _ = render_gauge(
                ctx,
                self.ratio,
                self.width.unwrap_or(DEFAULT_GAUGE_WIDTH),
                self.label.as_deref().unwrap_or(""),
                self.color,
            );
        }
    }
}

/// Single-line gauge builder. Auto-renders on `Drop`.
///
/// Constructed via [`Context::line_gauge`]. Chainable methods configure the
/// gauge before it renders. Drop to render without capturing a response, or
/// call [`Self::show`] to render and obtain a [`GaugeResponse`].
///
/// `Drop` is intentional: `ui.line_gauge(0.5).filled('━');` is the idiomatic
/// form when the response isn't needed.
///
/// # Family
///
/// Use [`Gauge`] for a block-fill bar with a centered label, or
/// [`Context::progress_bar`] / [`Context::progress`] for an unlabeled bar.
pub struct LineGauge<'a> {
    ctx: Option<&'a mut Context>,
    ratio: f64,
    label: Option<String>,
    width: Option<u32>,
    filled: char,
    empty: char,
}

impl<'a> LineGauge<'a> {
    fn new(ctx: &'a mut Context, ratio: f64) -> Self {
        Self {
            ctx: Some(ctx),
            ratio,
            label: None,
            width: None,
            filled: '━',
            empty: '─',
        }
    }

    /// Set the trailing label, appended after the bar.
    ///
    /// Accepts both `&str` and owned `String` via `impl Into<String>` so
    /// callers with already-owned strings (e.g. `format!(...)`) don't pay a
    /// redundant clone.
    pub fn label(mut self, label: impl Into<String>) -> Self {
        let label = label.into();
        if label.is_empty() {
            self.label = None;
        } else {
            self.label = Some(label);
        }
        self
    }

    /// Set the bar width in terminal cells (default: 20).
    pub fn width(mut self, w: u32) -> Self {
        self.width = Some(w);
        self
    }

    /// Set the filled character (default: `'━'`).
    pub fn filled(mut self, ch: char) -> Self {
        self.filled = ch;
        self
    }

    /// Set the empty character (default: `'─'`).
    pub fn empty(mut self, ch: char) -> Self {
        self.empty = ch;
        self
    }

    /// Render now and return the [`GaugeResponse`].
    pub fn show(mut self) -> GaugeResponse {
        let Some(ctx) = self.ctx.take() else {
            // `show` consumes the builder, so safe code cannot reach this
            // branch. Stay defensive if the internal invariant changes.
            return GaugeResponse::default();
        };
        render_line_gauge(
            ctx,
            self.ratio,
            self.width.unwrap_or(DEFAULT_GAUGE_WIDTH),
            self.filled,
            self.empty,
            self.label.as_deref(),
        )
    }
}

impl Drop for LineGauge<'_> {
    fn drop(&mut self) {
        if let Some(ctx) = self.ctx.take() {
            let _ = render_line_gauge(
                ctx,
                self.ratio,
                self.width.unwrap_or(DEFAULT_GAUGE_WIDTH),
                self.filled,
                self.empty,
                self.label.as_deref(),
            );
        }
    }
}

/// Internal rendering for a block-fill gauge.
fn render_gauge(
    ctx: &mut Context,
    ratio: f64,
    width: u32,
    label: &str,
    color_override: Option<Color>,
) -> GaugeResponse {
    let response = ctx.interaction();
    let clamped = finite_gauge_ratio(ratio);
    let width = width.max(1);
    let bar = compose_block_bar(clamped, width, label);
    let color = color_override.unwrap_or_else(|| gauge_color_for(ctx, clamped));
    ctx.styled(bar, Style::new().fg(color));
    GaugeResponse {
        response,
        ratio: clamped,
    }
}

/// Internal rendering for a single-line gauge.
fn render_line_gauge(
    ctx: &mut Context,
    ratio: f64,
    width: u32,
    filled: char,
    empty: char,
    label: Option<&str>,
) -> GaugeResponse {
    let response = ctx.interaction();
    let clamped = finite_gauge_ratio(ratio);
    let width = width.max(1);
    let bar = compose_line_bar(clamped, width, filled, empty, label);
    let color = gauge_color_for(ctx, clamped);
    ctx.styled(bar, Style::new().fg(color));
    GaugeResponse {
        response,
        ratio: clamped,
    }
}

fn finite_gauge_ratio(ratio: f64) -> f64 {
    if ratio.is_finite() {
        ratio.clamp(0.0, 1.0)
    } else {
        0.0
    }
}

/// Pick a color from the theme based on the current ratio.
///
/// `success` < 50%, `warning` 50–80%, `error` >= 80%.
fn gauge_color_for(ctx: &Context, ratio: f64) -> Color {
    if ratio >= 0.80 {
        ctx.theme.error
    } else if ratio >= 0.50 {
        ctx.theme.warning
    } else {
        ctx.theme.success
    }
}

/// How a label is positioned relative to the bar cells.
enum LabelMode<'a> {
    /// Overlay the label on top of the bar, centered. If the bar is too narrow
    /// to fit `label_w + 2`, the label is omitted entirely (not truncated).
    Centered(&'a str),
    /// Append the label after the bar, separated by a single space. Empty or
    /// missing labels emit nothing.
    Trailing(Option<&'a str>),
}

/// Compute the filled-cell count for `ratio`, clamped to `[0, width]`.
///
/// Internal math runs in `f64` (the public ratio type) and only crosses to
/// `u32` at this boundary — keeps `compose_*_bar` precision-stable.
fn filled_cells(ratio: f64, width: u32) -> u32 {
    let count = (ratio * f64::from(width)).round() as u32;
    count.min(width)
}

/// Shared bar-composition core for `compose_block_bar` / `compose_line_bar`.
///
/// Builds `width` cells (filled or empty) and overlays/appends the label
/// according to `mode`. Unicode width is honored for centered overlays so
/// multi-byte labels (e.g. CJK) line up correctly.
fn compose_bar(
    ratio: f64,
    width: u32,
    fill_ch: char,
    empty_ch: char,
    mode: LabelMode<'_>,
) -> String {
    let width_usize = width as usize;
    let filled = filled_cells(ratio, width);

    if let LabelMode::Centered(label) = mode
        && !label.is_empty()
    {
        let label_w = UnicodeWidthStr::width(label);
        if label_w + 2 <= width_usize {
            // Build the bar then overlay the centered label.
            let mut cells: Vec<String> = Vec::with_capacity(width_usize);
            for i in 0..width {
                cells.push(if i < filled {
                    fill_ch.to_string()
                } else {
                    empty_ch.to_string()
                });
            }
            let label_start = (width_usize.saturating_sub(label_w)) / 2;
            crate::chart::write_text_cells(&mut cells, label_start, label);
            return cells.concat();
        }
    }

    // Plain bar (no label, label too wide, or trailing mode).
    let trailing = match mode {
        LabelMode::Trailing(Some(lbl)) if !lbl.is_empty() => Some(lbl),
        _ => None,
    };
    let mut out = String::with_capacity(
        width_usize * fill_ch.len_utf8().max(empty_ch.len_utf8())
            + trailing.map_or(0, |s| s.len() + 1),
    );
    for _ in 0..filled {
        out.push(fill_ch);
    }
    for _ in 0..width.saturating_sub(filled) {
        out.push(empty_ch);
    }
    if let Some(lbl) = trailing {
        out.push(' ');
        out.push_str(lbl);
    }
    out
}

/// Build a block-style bar (`█` filled, `░` empty) of `width` cells with an
/// optional centered `label`. The label is omitted (not truncated) when the
/// bar is too narrow to fit it.
fn compose_block_bar(ratio: f64, width: u32, label: &str) -> String {
    compose_bar(ratio, width, '█', '░', LabelMode::Centered(label))
}

/// Build a single-line bar with configurable fill/empty chars and optional
/// label appended after the bar (not centered inside).
fn compose_line_bar(
    ratio: f64,
    width: u32,
    filled: char,
    empty: char,
    label: Option<&str>,
) -> String {
    compose_bar(ratio, width, filled, empty, LabelMode::Trailing(label))
}

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

    #[test]
    fn block_bar_no_label() {
        let bar = compose_block_bar(0.5, 10, "");
        assert_eq!(bar, "█████░░░░░");
    }

    #[test]
    fn block_bar_with_label() {
        let bar = compose_block_bar(0.5, 12, "50%");
        assert!(bar.contains("50%"), "label visible: {bar}");
        // The label sits on the bar — total cells unchanged.
        assert_eq!(UnicodeWidthStr::width(bar.as_str()), 12);
    }

    #[test]
    fn block_bar_cjk_label_keeps_exact_cell_width() {
        let bar = compose_block_bar(0.5, 12, "한글");
        assert!(bar.contains("한글"));
        assert_eq!(UnicodeWidthStr::width(bar.as_str()), 12);
    }

    #[test]
    fn block_bar_omits_label_when_too_narrow() {
        // "12345" is 5 wide; bar of 6 has only 4 free cells (need label_w + 2).
        let bar = compose_block_bar(0.5, 6, "12345");
        assert!(!bar.contains("12345"));
        assert_eq!(UnicodeWidthStr::width(bar.as_str()), 6);
    }

    #[test]
    fn line_bar_default_chars() {
        let bar = compose_line_bar(0.5, 10, '━', '─', None);
        assert_eq!(bar, "━━━━━─────");
    }

    #[test]
    fn line_bar_appends_label() {
        let bar = compose_line_bar(1.0, 4, '#', '.', Some("done"));
        assert_eq!(bar, "#### done");
    }

    #[test]
    fn block_bar_f64_precision() {
        // Ratios that f32 rounds differently from f64 still produce stable
        // block counts — confirms internal math runs in f64.
        let bar = compose_block_bar(1.0 / 3.0, 30, "");
        let filled = bar.chars().filter(|&c| c == '█').count();
        // (1/3 * 30).round() == 10
        assert_eq!(filled, 10);
    }

    #[test]
    fn non_finite_gauge_ratios_resolve_to_zero_in_response() {
        let mut backend = crate::TestBackend::new(30, 4);
        let mut gauge_ratio = 1.0;
        let mut line_ratio = 1.0;
        backend.render(|ui| {
            gauge_ratio = ui.gauge(f64::NAN).show().ratio;
            line_ratio = ui.line_gauge(f64::INFINITY).show().ratio;
        });
        assert_eq!(gauge_ratio, 0.0);
        assert_eq!(line_ratio, 0.0);
    }
}