retroglyph_ui/

style.rs

//! [`BoxStyle`]: a Lip-Gloss-style box model (padding, border, margin).
//!
//! Renders content into a standalone [`Grid`], independent of any
//! [`Backend`](retroglyph_core::backend::Backend)/[`Terminal`](retroglyph_core::terminal::Terminal).
//!
//! For a box drawn straight into a [`Surface`](crate::Surface) you already own -- with titles,
//! `BorderType` glyph sets, and theming -- use [`Panel`](crate::widget::Panel) instead. Reach
//! for `BoxStyle` when composing a box outside a frame, laying boxes out with
//! [`join_h`](crate::block::join_h)/[`join_v`](crate::block::join_v), or needing `margin` (space
//! outside the border, which `Panel` has no concept of).
//!
//! `BoxStyle` does not word-wrap: it lays out already-broken lines (only
//! `'\n'` is treated specially).
//!
//! For word-wrapping text to a width first, use `Paragraph`, then hand the
//! wrapped result to `BoxStyle::render`. Keeping wrapping and box-model
//! layout separate avoids tying every consumer of this module to `Paragraph`
//! or the `egc` feature.
use alloc::vec::Vec;

use retroglyph_core::color::Style;
use retroglyph_core::grid::Grid;
use retroglyph_core::text::{char_width, width_usize as measured_width};
use retroglyph_core::tile::Tile;
// `Rect` and `HasSize` are only named by the `egc` content-measuring path below and by this
// module's tests.
#[cfg(feature = "egc")]
use retroglyph_core::grid::{HasSize, Rect};

use crate::Surface;
use crate::text::truncate;
use crate::widget::Widget;
use retroglyph_core::symbols::border::PLAIN;

/// CSS-style box-model sides: top/right/bottom/left, in terminal cells.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct Sides {
    /// Cells above.
    pub top: u16,
    /// Cells to the right.
    pub right: u16,
    /// Cells below.
    pub bottom: u16,
    /// Cells to the left.
    pub left: u16,
}

impl Sides {
    /// No space on any side.
    pub const ZERO: Self = Self {
        top: 0,
        right: 0,
        bottom: 0,
        left: 0,
    };

    /// The same number of cells on all four sides.
    #[must_use]
    pub const fn all(n: u16) -> Self {
        Self {
            top: n,
            right: n,
            bottom: n,
            left: n,
        }
    }

    /// `vertical` cells top/bottom, `horizontal` cells left/right (CSS
    /// `padding: v h` shorthand).
    #[must_use]
    pub const fn symmetric(vertical: u16, horizontal: u16) -> Self {
        Self {
            top: vertical,
            right: horizontal,
            bottom: vertical,
            left: horizontal,
        }
    }

    /// Returns `self` with `top` replaced.
    #[must_use]
    pub const fn top(mut self, top: u16) -> Self {
        self.top = top;
        self
    }

    /// Returns `self` with `right` replaced.
    #[must_use]
    pub const fn right(mut self, right: u16) -> Self {
        self.right = right;
        self
    }

    /// Returns `self` with `bottom` replaced.
    #[must_use]
    pub const fn bottom(mut self, bottom: u16) -> Self {
        self.bottom = bottom;
        self
    }

    /// Returns `self` with `left` replaced.
    #[must_use]
    pub const fn left(mut self, left: u16) -> Self {
        self.left = left;
        self
    }

    const fn horizontal(self) -> u16 {
        self.left.saturating_add(self.right)
    }

    const fn vertical(self) -> u16 {
        self.top.saturating_add(self.bottom)
    }
}

/// A box-model wrapper: content, padding, an optional single-line border,
/// and margin, rendered into a standalone [`Grid`] via [`BoxStyle::render`].
///
/// Layers from the inside out: content -> padding -> border -> margin.
/// Margin cells are left empty (transparent, per [`Grid::new`]'s default
/// tiles), matching CSS margin being outside the box's own background.
///
/// See [`Panel`](crate::widget::Panel) for drawing a bordered, titled box directly into a
/// [`Surface`](crate::Surface) instead.
///
/// # Examples
///
/// ```
/// use retroglyph_core::color::Style;
/// use retroglyph_core::grid::Pos;
/// use retroglyph_ui::style::{BoxStyle, Sides};
///
/// let grid = BoxStyle::new(Style::new())
///     .border(true)
///     .padding(Sides::all(1))
///     .render("hi");
/// assert_eq!(grid[Pos::new(2, 2)].glyph(), 'h'); // 1 border + 1 padding cell in from the corner
/// ```
#[derive(Clone, Copy, Debug)]
pub struct BoxStyle {
    style: Style,
    padding: Sides,
    margin: Sides,
    border: bool,
    width: Option<u16>,
    height: Option<u16>,
}

impl BoxStyle {
    /// A borderless box with no padding/margin, in `style`, sized to fit its
    /// content.
    #[must_use]
    pub const fn new(style: Style) -> Self {
        Self {
            style,
            padding: Sides::ZERO,
            margin: Sides::ZERO,
            border: false,
            width: None,
            height: None,
        }
    }

    /// Sets the padding, between the border (if any) and the content.
    #[must_use]
    pub const fn padding(mut self, padding: Sides) -> Self {
        self.padding = padding;
        self
    }

    /// Sets the margin, outside the border (if any); left transparent.
    #[must_use]
    pub const fn margin(mut self, margin: Sides) -> Self {
        self.margin = margin;
        self
    }

    /// Draws a single-line border, in `style`, around the padding.
    #[must_use]
    pub const fn border(mut self, border: bool) -> Self {
        self.border = border;
        self
    }

    /// Sets an explicit content width (excludes padding/border/margin).
    ///
    /// Lines wider than this are clipped; without this, the box sizes to
    /// its widest content line.
    #[must_use]
    pub const fn width(mut self, width: u16) -> Self {
        self.width = Some(width);
        self
    }

    /// Sets an explicit content height (excludes padding/border/margin).
    ///
    /// Lines past this are dropped; without this, the box sizes to the
    /// number of lines in the content.
    #[must_use]
    pub const fn height(mut self, height: u16) -> Self {
        self.height = Some(height);
        self
    }

    /// Renders `text` into a standalone [`Grid`]: content, padding, border,
    /// and margin, in that order from the inside out.
    ///
    /// `text` is split only on `'\n'`; it is not word-wrapped (see the
    /// module docs).
    ///
    /// Content is positioned by display column (via `retroglyph_core::text`), so a
    /// wide (2-column) character correctly pushes later characters on the
    /// same line over by 2 columns rather than 1, and gets a proper
    /// `WIDE_CHAR_SPACER` reservation on the cell to its right, courtesy of
    /// `retroglyph_core::grid::Grid::put_tile` (wide-char aware on every feature
    /// combination, not just `egc`; this module still does not depend on it).
    #[must_use]
    pub fn render(&self, text: &str) -> Grid {
        let lines: Vec<&str> = text.split('\n').collect();
        let content_w = self.width.unwrap_or_else(|| {
            u16::try_from(lines.iter().map(|l| measured_width(l)).max().unwrap_or(0))
                .unwrap_or(u16::MAX)
        });
        let content_h = self
            .height
            .unwrap_or_else(|| u16::try_from(lines.len()).unwrap_or(u16::MAX));

        let (mut grid, content_x, content_y) = self.scaffold(content_w, content_h);
        for (row, line) in lines.iter().take(usize::from(content_h)).enumerate() {
            let Ok(row) = u16::try_from(row) else { break };
            let clipped = truncate(line, content_w);
            let mut col = 0u16;
            for ch in clipped.chars() {
                let w = char_width(ch);
                if col.saturating_add(w) > content_w {
                    break;
                }
                grid.put_tile(
                    0,
                    (content_x.saturating_add(col), content_y.saturating_add(row)),
                    Tile::new(ch, self.style),
                );
                col = col.saturating_add(w);
            }
        }
        grid
    }

    /// Word-wraps `text` to this box's content width, then renders it the
    /// same way as [`render`](Self::render): content, padding, border, and
    /// margin, from the inside out.
    ///
    /// Requires the `egc` feature: wrapping is delegated to
    /// `retroglyph_core::layout::TextLayout`, which (unlike `render`) also
    /// places wide characters correctly, with a proper `WIDE_CHAR_SPACER`.
    /// If no explicit width was set via [`BoxStyle::width`], `text` is
    /// measured but not wrapped (there is no width to wrap to), matching
    /// `render`'s own natural-width fallback.
    #[cfg(feature = "egc")]
    #[must_use]
    pub fn render_wrapped(&self, text: &str) -> Grid {
        use retroglyph_core::layout::TextLayout;
        use retroglyph_core::text::{Line, Span};

        let content_w = self.width.unwrap_or_else(|| {
            u16::try_from(text.split('\n').map(measured_width).max().unwrap_or(0))
                .unwrap_or(u16::MAX)
        });
        let line = Line::from(Span::styled(text, self.style));
        let content_h = self.height.unwrap_or_else(|| {
            TextLayout::new(&line)
                .rect(Rect::new(0, 0, content_w, u16::MAX))
                .measure()
                .height()
        });

        let (mut grid, content_x, content_y) = self.scaffold(content_w, content_h);
        TextLayout::new(&line)
            .rect(Rect::new(content_x, content_y, content_w, content_h))
            .render_to_grid(&mut grid, 0);

        grid
    }

    /// Builds the padding/border/margin scaffold for a `content_w`x`content_h`
    /// content area: a fresh [`Grid`] with the box's background (and border,
    /// if any) already drawn, plus the `(x, y)` offset where content should
    /// be written.
    fn scaffold(&self, content_w: u16, content_h: u16) -> (Grid, u16, u16) {
        let border_wh = u16::from(self.border) * 2;
        let inner_w = content_w
            .saturating_add(self.padding.horizontal())
            .saturating_add(border_wh);
        let inner_h = content_h
            .saturating_add(self.padding.vertical())
            .saturating_add(border_wh);
        let outer_w = inner_w.saturating_add(self.margin.horizontal()).max(1);
        let outer_h = inner_h.saturating_add(self.margin.vertical()).max(1);

        let mut grid = Grid::new(outer_w, outer_h);
        let box_x = self.margin.left;
        let box_y = self.margin.top;

        fill_rect(&mut grid, box_x, box_y, inner_w, inner_h, self.style);
        if self.border {
            // `inner_w`/`inner_h` already include the border's own 2 cells
            // (`border_wh` above), so both are always >= 2 here.
            draw_border(&mut grid, box_x, box_y, inner_w, inner_h, self.style);
        }

        let content_x = box_x
            .saturating_add(u16::from(self.border))
            .saturating_add(self.padding.left);
        let content_y = box_y
            .saturating_add(u16::from(self.border))
            .saturating_add(self.padding.top);
        (grid, content_x, content_y)
    }
}

/// Pairs a [`BoxStyle`] with the text it should render, so the pair can
/// implement [`Widget`] (which has no room for a text parameter). Build one
/// via [`BoxStyle::text`].
///
/// [`Widget::render`] places the box at `area`'s top-left corner, sized to
/// the style's own explicit-or-content-fit dimensions: it does not stretch
/// or clip to fill `area`. It always uses [`BoxStyle::render`] (not
/// `BoxStyle::render_wrapped`, behind the `egc` feature); for wrapped
/// content, call `render_wrapped` directly and
/// [`Surface::blit`](retroglyph_core::surface::Surface::blit) the result yourself.
#[derive(Clone, Copy, Debug)]
pub struct Boxed<'a> {
    style: BoxStyle,
    text: &'a str,
}

impl BoxStyle {
    /// Pairs this style with `text`, ready to draw via [`Widget::render`].
    #[must_use]
    pub const fn text(self, text: &str) -> Boxed<'_> {
        Boxed { style: self, text }
    }
}

impl Widget for Boxed<'_> {
    fn render(&self, surface: &mut Surface<'_>) {
        let grid = self.style.render(self.text);
        // `(0, 0)` in this surface's own local coordinates is its area's own top-left corner.
        surface.blit(&grid, 0, 0);
    }
}

/// Fill `w`×`h` starting at `(x, y)` with a `style`d space.
fn fill_rect(grid: &mut Grid, x: u16, y: u16, w: u16, h: u16, style: Style) {
    for dy in 0..h {
        for dx in 0..w {
            grid.put_tile(0, (x + dx, y + dy), Tile::new(' ', style));
        }
    }
}

/// Draw a single-line border around the `w`×`h` rect at `(x, y)`, in
/// `style`. Caller must ensure `w >= 2 && h >= 2`.
fn draw_border(grid: &mut Grid, x: u16, y: u16, w: u16, h: u16, style: Style) {
    let right = x + w - 1;
    let bottom = y + h - 1;

    grid.put_tile(0, (x, y), Tile::new(PLAIN.top_left, style));
    grid.put_tile(0, (right, y), Tile::new(PLAIN.top_right, style));
    grid.put_tile(0, (x, bottom), Tile::new(PLAIN.bottom_left, style));
    grid.put_tile(0, (right, bottom), Tile::new(PLAIN.bottom_right, style));
    for cx in (x + 1)..right {
        grid.put_tile(0, (cx, y), Tile::new(PLAIN.horizontal, style));
        grid.put_tile(0, (cx, bottom), Tile::new(PLAIN.horizontal, style));
    }
    for cy in (y + 1)..bottom {
        grid.put_tile(0, (x, cy), Tile::new(PLAIN.vertical, style));
        grid.put_tile(0, (right, cy), Tile::new(PLAIN.vertical, style));
    }
}

#[cfg(test)]
mod tests {
    use alloc::string::String;

    use super::*;
    use retroglyph_core::grid::{Pos, Rect};

    fn glyphs(grid: &Grid) -> Vec<String> {
        (0..grid.height())
            .map(|y| {
                (0..grid.width())
                    .map(|x| grid[Pos::new(x, y)].glyph())
                    .collect()
            })
            .collect()
    }

    #[test]
    fn boxed_render_draws_on_a_surface_that_is_not_on_layer_zero() {
        // The retroglyph#824 regression: `Boxed` renders its `BoxStyle` into a standalone,
        // layer-0-only `Grid` and stamps it onto the caller's surface, which must still work
        // when that surface is on a non-zero layer (e.g. `surface.on_tier(Layer::Overlay)`, as
        // `Modal`'s own docs recommend for overlay content).
        use retroglyph_core::surface::{Layer, Surface};

        let mut grid = Grid::new(6, 3);
        let mut surface = Surface::new(&mut grid, Rect::new(0, 0, 6, 3), Layer::World.as_u8());
        let boxed = BoxStyle::new(Style::default()).text("hi");
        boxed.render(&mut surface.on_tier(Layer::Overlay));

        assert_eq!(
            grid.tile(Layer::Overlay.as_u8(), (0, 0)).map(Tile::glyph),
            Some('h')
        );
        assert_eq!(
            grid.tile(Layer::Overlay.as_u8(), (1, 0)).map(Tile::glyph),
            Some('i')
        );
    }

    #[test]
    fn sides_helpers() {
        assert_eq!(
            Sides::all(2),
            Sides {
                top: 2,
                right: 2,
                bottom: 2,
                left: 2
            }
        );
        assert_eq!(
            Sides::symmetric(1, 3),
            Sides {
                top: 1,
                right: 3,
                bottom: 1,
                left: 3
            }
        );
    }

    #[test]
    fn sizes_to_content_with_no_padding_or_border() {
        let grid = BoxStyle::new(Style::default()).render("hi");
        assert_eq!((grid.width(), grid.height()), (2, 1));
        assert_eq!(grid[Pos::new(0, 0)].glyph(), 'h');
        assert_eq!(grid[Pos::new(1, 0)].glyph(), 'i');
    }

    #[test]
    fn sizes_to_the_widest_of_multiple_lines() {
        let grid = BoxStyle::new(Style::default()).render("a\nbcd\nef");
        assert_eq!((grid.width(), grid.height()), (3, 3));
        assert_eq!(grid[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(grid[Pos::new(1, 0)].glyph(), ' '); // shorter line padded with blanks
        assert_eq!(grid[Pos::new(0, 1)].glyph(), 'b');
        assert_eq!(grid[Pos::new(2, 1)].glyph(), 'd');
    }

    #[test]
    fn explicit_width_clips_longer_lines_and_pads_shorter_ones() {
        let grid = BoxStyle::new(Style::default()).width(3).render("hello");
        assert_eq!(grid.width(), 3);
        let row: String = (0..3).map(|x| grid[Pos::new(x, 0)].glyph()).collect();
        assert_eq!(row, "hel");
    }

    #[test]
    fn explicit_height_drops_extra_lines() {
        let grid = BoxStyle::new(Style::default()).height(1).render("a\nb\nc");
        assert_eq!(grid.height(), 1);
        assert_eq!(grid[Pos::new(0, 0)].glyph(), 'a');
    }

    #[test]
    fn padding_surrounds_content_with_the_box_style() {
        let grid = BoxStyle::new(Style::default())
            .padding(Sides::all(1))
            .render("x");
        // 1 content col/row + 1 padding on each side = 3x3.
        assert_eq!((grid.width(), grid.height()), (3, 3));
        assert_eq!(grid[Pos::new(1, 1)].glyph(), 'x');
        assert_eq!(grid[Pos::new(0, 0)].glyph(), ' ');
    }

    #[test]
    fn render_does_not_overflow_on_a_near_u16_max_line_with_padding() {
        // retroglyph#729: `content_x + col` used to overflow `u16` once padding pushed the write
        // position past `u16::MAX` for a line wide enough to fill the content area to its edge.
        let text = "a".repeat(65_535);
        let grid = BoxStyle::new(Style::default())
            .padding(Sides::all(2))
            .render(&text);
        assert_eq!(grid[Pos::new(2, 2)].glyph(), 'a');
    }

    #[test]
    fn border_draws_a_box_around_padding_and_content() {
        let grid = BoxStyle::new(Style::default()).border(true).render("x");
        // 1 content col/row + 2 border = 3x3.
        assert_eq!((grid.width(), grid.height()), (3, 3));
        let rows = glyphs(&grid);
        assert_eq!(rows[0], "┌─┐");
        assert_eq!(rows[1], "│x│");
        assert_eq!(rows[2], "└─┘");
    }

    #[test]
    fn margin_is_left_transparent_outside_the_border() {
        let grid = BoxStyle::new(Style::default())
            .margin(Sides::all(1))
            .render("x");
        // 1x1 content, 1 margin on each side = 3x3; margin cells are never
        // written, so they keep Grid::new's default "empty" tile, which
        // Grid::blit treats as transparent.
        assert_eq!((grid.width(), grid.height()), (3, 3));
        assert!(grid[Pos::new(0, 0)].is_empty());
        assert_eq!(grid[Pos::new(1, 1)].glyph(), 'x');
    }

    #[test]
    fn wide_characters_push_later_columns_over_by_their_width() {
        use retroglyph_core::tile::TileFlags;

        // "あ" (HIRAGANA A) is 2 columns wide: width("aあb") == 4, and 'b'
        // must land at column 3, not column 2 (its char index), or it would
        // collide with あ's second visual column.
        let grid = BoxStyle::new(Style::default()).render("aあb");
        assert_eq!(grid.width(), 4);
        assert_eq!(grid[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(grid[Pos::new(1, 0)].glyph(), 'あ');
        // `put_tile` reserves a proper `WIDE_CHAR_SPACER` at the wide glyph's right half.
        assert!(
            grid[Pos::new(2, 0)]
                .flags()
                .contains(TileFlags::WIDE_CHAR_SPACER)
        );
        assert_eq!(grid[Pos::new(3, 0)].glyph(), 'b');
    }

    #[test]
    fn control_characters_occupy_one_column_matching_core_text_char_width() {
        // retroglyph#760: this crate's own char-width loop used to answer `0` columns for a
        // control character (`ch.width().unwrap_or(0)`), disagreeing with `Surface`/`Tile`, which
        // both already advance one column when a control character is drawn. Routing through
        // `retroglyph_core::text::char_width` (now `unwrap_or(1)`) makes a BEL take up a column
        // here too, so "a\u{7}b" is 3 columns wide, not 2.
        let grid = BoxStyle::new(Style::default()).render("a\u{7}b");
        assert_eq!(grid.width(), 3);
        assert_eq!(grid[Pos::new(0, 0)].glyph(), 'a');
        assert_eq!(grid[Pos::new(2, 0)].glyph(), 'b');
    }

    #[test]
    fn border_with_empty_content_is_still_at_least_a_2x2_box() {
        // No content, no padding: inner size is exactly the border's own 2
        // cells in each axis (content_w = 0, content_h = 1 line of "").
        let grid = BoxStyle::new(Style::default()).border(true).render("");
        assert_eq!((grid.width(), grid.height()), (2, 3));
        let rows = glyphs(&grid);
        assert_eq!(rows[0], "┌┐");
        assert_eq!(rows[2], "└┘");
    }

    #[test]
    #[cfg(feature = "egc")]
    fn render_wrapped_word_wraps_to_the_explicit_width() {
        // Same text/width Paragraph's own tests use (see widget/paragraph.rs),
        // so this is exercising the same, already-verified TextLayout wrap.
        let grid = BoxStyle::new(Style::default())
            .width(10)
            .render_wrapped("the quick brown fox jumps");
        assert_eq!(grid.width(), 10);
        let rows = glyphs(&grid);
        assert_eq!(rows[0].trim_end(), "the quick");
        assert_eq!(rows[1].trim_end(), "brown fox");
        assert_eq!(rows[2].trim_end(), "jumps");
    }

    #[test]
    #[cfg(feature = "egc")]
    fn render_wrapped_without_an_explicit_width_measures_but_does_not_wrap() {
        // No width set: same natural-width fallback as `render`, so nothing
        // is short enough to need wrapping.
        let grid = BoxStyle::new(Style::default()).render_wrapped("hi");
        assert_eq!((grid.width(), grid.height()), (2, 1));
        assert_eq!(grid[Pos::new(0, 0)].glyph(), 'h');
        assert_eq!(grid[Pos::new(1, 0)].glyph(), 'i');
    }

    #[test]
    #[cfg(feature = "egc")]
    fn render_wrapped_respects_padding_and_border_like_render() {
        let grid = BoxStyle::new(Style::default())
            .border(true)
            .padding(Sides::all(1))
            .width(3)
            .render_wrapped("hi");
        // 3 content cols + 2 padding + 2 border = 7; 1 content row + 2
        // padding + 2 border = 5.
        assert_eq!((grid.width(), grid.height()), (7, 5));
        assert_eq!(grid[Pos::new(2, 2)].glyph(), 'h');
        assert_eq!(grid[Pos::new(3, 2)].glyph(), 'i');
    }

    #[test]
    fn boxed_widget_places_the_box_at_the_areas_top_left() {
        let styled = BoxStyle::new(Style::default()).border(true).text("hi");
        let area = Rect::new(2, 1, 10, 6);
        let mut grid = Grid::new(12, 7);
        styled.render(&mut Surface::new(&mut grid, area, 0));

        // 2 content cols + 2 border = 4 wide, 1 content row + 2 border = 3
        // tall, anchored at (2, 1) regardless of the much larger area.
        assert_eq!(grid[Pos::new(2, 1)].glyph(), '┌');
        assert_eq!(grid[Pos::new(3, 2)].glyph(), 'h');
        assert_eq!(grid[Pos::new(4, 2)].glyph(), 'i');
        assert_eq!(grid[Pos::new(5, 3)].glyph(), '┘');
    }
}