htui 0.2.0

A terminal HTML/CSS renderer with an embedded JavaScript engine — build interactive TUIs from HTML, CSS and JS
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

use std::{
    fmt::{self, Display},
    ops::{Deref, DerefMut},
};

use bitflags::bitflags;
use compact_str::CompactString;
use crossterm::style::{Color, StyledContent, Stylize};

bitflags! {
    /// Display flags applied to a [`Block`].
    ///
    /// Aggregates the independent CSS font/text properties we render
    /// (`font-weight: bold`, `font-style: italic`, `text-decoration:
    /// underline`, `text-decoration: line-through`) into one bitfield so a
    /// single character cell can carry any combination without growing the
    /// `Block` shape on every new style attribute.
    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
    pub struct FontStyle: u8 {
        const BOLD        = 0b0000_0001;
        const ITALIC      = 0b0000_0010;
        const UNDERLINED  = 0b0000_0100;
        const CROSSED_OUT = 0b0000_1000;
    }
}

/// One terminal character cell: a grapheme cluster plus its foreground /
/// background colors and [`FontStyle`] flags. A cell grid of these is the
/// unit the diff renderer compares and the ANSI writer serializes.
#[derive(Debug, Clone)]
pub struct Block {
    pub word: CompactString,
    pub fcolor: Option<Color>,
    pub bcolor: Option<Color>,
    pub style: FontStyle,
}

impl Deref for Block {
    type Target = str;
    fn deref(&self) -> &Self::Target {
        &self.word
    }
}

impl DerefMut for Block {
    fn deref_mut(&mut self) -> &mut str {
        &mut self.word
    }
}

impl Display for Block {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{}",
            styled_string(&self.word, self.style, self.fcolor, self.bcolor)
        )
    }
}

/// Apply a [`FontStyle`] bitfield and optional foreground/background colors to
/// `text` and return the [`StyledContent`] wrapper (borrowing `text`) ready
/// for display.
///
/// Used by both [`Block`]'s `Display` impl and the render path so the SGR
/// emission lives in one place. Returning the wrapper instead of a formatted
/// `String` lets callers write the ANSI bytes straight into their output
/// buffer (`Vec<u8>` via `io::Write`, or a `fmt::Formatter` via `fmt::Write`)
/// without an intermediate heap allocation per styled run.
pub(crate) fn styled_string(
    text: &str,
    style: FontStyle,
    fg: Option<Color>,
    bg: Option<Color>,
) -> StyledContent<&str> {
    let mut styled = text.stylize();
    if style.contains(FontStyle::BOLD) {
        styled = styled.bold();
    }
    if style.contains(FontStyle::ITALIC) {
        styled = styled.italic();
    }
    if style.contains(FontStyle::UNDERLINED) {
        styled = styled.underlined();
    }
    if style.contains(FontStyle::CROSSED_OUT) {
        styled = styled.crossed_out();
    }
    match (fg, bg) {
        (Some(f), Some(b)) => styled.with(f).on(b),
        (Some(f), None) => styled.with(f),
        (None, Some(b)) => styled.on(b),
        (None, None) => styled,
    }
}

impl Default for Block {
    /// A blank cell: a single space with no color, no style, and no
    /// foreground/background. Used as the starting state for the canvas
    /// (`vec![Block::default(); n]`) and as a reusable template by the
    /// painters, avoiding repeated `" ".to_string()` construction.
    ///
    /// `CompactString` stores every grapheme cluster up to 24 bytes fully
    /// inline (ASCII, CJK, box-drawing glyphs, flags, skin-tone and keycap
    /// sequences), so per-cell canvas init / clone / diff never touches the
    /// heap. Longer clusters (multi-person ZWJ emoji) transparently fall
    /// back to one heap allocation.
    fn default() -> Self {
        let word = CompactString::new(" ");
        Self {
            word,
            fcolor: None,
            bcolor: None,
            style: FontStyle::empty(),
        }
    }
}

impl Block {
    /// Create a cell from its text, foreground/background colors, and style bits.
    pub fn new(
        word: String,
        fcolor: Option<Color>,
        bcolor: Option<Color>,
        style: FontStyle,
    ) -> Self {
        Self {
            word: word.into(),
            fcolor,
            bcolor,
            style,
        }
    }
}