tui-banner 0.2.1

Colorful ASCII art banner renderer for Rust CLI/TUI
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
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

// Copyright (c) 2025 Lei Zhang
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

use crate::color::Color;
use crate::grid::Grid;

/// Direction of the light sweep.
#[derive(Clone, Copy, Debug)]
pub enum SweepDirection {
    /// Sweep left to right.
    Horizontal,
    /// Sweep top to bottom.
    Vertical,
    /// Sweep from top-left to bottom-right.
    DiagonalDown,
    /// Sweep from bottom-left to top-right.
    DiagonalUp,
}

/// Highlight sweep configuration.
#[derive(Clone, Copy, Debug)]
pub struct LightSweep {
    /// Center position along the sweep axis (0.0..1.0, values outside are allowed for off-screen).
    pub center: f32,
    /// Width of the sweep band along the axis (0.0..1.0).
    pub width: f32,
    /// Peak brightening amount (0.0..1.0).
    pub intensity: f32,
    /// Falloff curve exponent (>= 1.0).
    pub softness: f32,
    /// Sweep direction.
    pub direction: SweepDirection,
}

impl LightSweep {
    /// Create a sweep with sensible defaults.
    pub fn new(direction: SweepDirection) -> Self {
        Self {
            center: 0.5,
            width: 0.25,
            intensity: 0.8,
            softness: 2.0,
            direction,
        }
    }

    /// Set the sweep center (0.0..1.0).
    pub fn center(mut self, center: f32) -> Self {
        self.center = center;
        self
    }

    /// Set the sweep width (0.0..1.0).
    pub fn width(mut self, width: f32) -> Self {
        self.width = width;
        self
    }

    /// Set the sweep intensity (0.0..1.0).
    pub fn intensity(mut self, intensity: f32) -> Self {
        self.intensity = intensity;
        self
    }

    /// Set the sweep falloff exponent (>= 1.0).
    pub fn softness(mut self, softness: f32) -> Self {
        self.softness = softness;
        self
    }
}

/// Apply a highlight sweep in-place.
pub fn apply_light_sweep(grid: &mut Grid, sweep: LightSweep) {
    apply_light_sweep_tint(grid, sweep, Color::Rgb(255, 255, 255));
}

/// Apply a highlight sweep in-place with a custom highlight color.
pub fn apply_light_sweep_tint(grid: &mut Grid, sweep: LightSweep, highlight: Color) {
    let height = grid.height().max(1);
    let width = grid.width().max(1);

    let intensity = sweep.intensity.clamp(0.0, 1.0);
    let band = sweep.width.max(0.0);
    if intensity <= 0.0 || band <= 0.0 {
        return;
    }

    let half = band / 2.0;
    let softness = sweep.softness.max(1.0);

    for r in 0..height {
        for c in 0..width {
            let Some(cell) = grid.cell_mut(r, c) else {
                continue;
            };
            if !cell.visible {
                continue;
            }

            let t = axis_t(sweep.direction, r, c, width, height);
            let dist = (t - sweep.center).abs();
            if dist > half {
                continue;
            }

            let falloff = 1.0 - (dist / half);
            let strength = falloff.powf(softness);
            let amount = (intensity * strength).clamp(0.0, 1.0);
            if amount <= 0.0 {
                continue;
            }

            if let Some(color) = cell.fg {
                cell.fg = Some(blend_to(color, highlight, amount));
            }
        }
    }
}

fn axis_t(direction: SweepDirection, row: usize, col: usize, width: usize, height: usize) -> f32 {
    match direction {
        SweepDirection::Horizontal => {
            if width <= 1 {
                0.0
            } else {
                col as f32 / (width - 1) as f32
            }
        }
        SweepDirection::Vertical => {
            if height <= 1 {
                0.0
            } else {
                row as f32 / (height - 1) as f32
            }
        }
        SweepDirection::DiagonalDown => {
            if width + height <= 2 {
                0.0
            } else {
                (row + col) as f32 / (width + height - 2) as f32
            }
        }
        SweepDirection::DiagonalUp => {
            if width + height <= 2 {
                0.0
            } else {
                (row + (width - 1 - col)) as f32 / (width + height - 2) as f32
            }
        }
    }
}

fn blend_to(color: Color, target: Color, amount: f32) -> Color {
    color.lerp(target, amount)
}