ratkit 0.2.16

A comprehensive collection of reusable TUI components for ratatui including resizable splits, tree views, markdown rendering, toast notifications, dialogs, and terminal embedding
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

//! Outline rendering and hit-testing for document viewers.

use ratatui::{
    buffer::Buffer,
    layout::Rect,
    style::{Color, Style},
    widgets::{Block, BorderType, Borders, Widget},
};

const PANEL_BG: Color = Color::Rgb(30, 32, 38);
const BORDER_FG: Color = Color::Rgb(138, 99, 210);
const TEXT_FG: Color = Color::Rgb(160, 160, 160);
const HOVER_BG: Color = Color::Rgb(60, 60, 70);
const COMPACT_LINE_FG: Color = Color::Rgb(120, 120, 130);

use crate::widgets::document_viewer::foundation::DocumentOutlineItem;

/// Renders document outline entries as a TOC overlay.
pub fn render_outline(
    area: Rect,
    buf: &mut Buffer,
    outline: &[DocumentOutlineItem],
    hovered: bool,
    hovered_entry: Option<usize>,
) {
    let Some(toc_area) = outline_overlay_area(area, outline.len(), hovered) else {
        return;
    };
    fill_background(toc_area, buf, Style::default().bg(PANEL_BG));
    render_outline_block(toc_area, buf);
    let inner = outline_inner_area(toc_area);
    if hovered {
        render_expanded_entries(inner, buf, outline, hovered_entry);
    } else {
        render_compact_marker(inner, buf);
    }
}

/// Returns the outline entry index under a terminal coordinate.
pub fn outline_entry_at_position(
    x: u16,
    y: u16,
    area: Rect,
    outline_len: usize,
    hovered: bool,
) -> Option<usize> {
    let toc_area = outline_overlay_area(area, outline_len, hovered)?;
    let inner = outline_inner_area(toc_area);
    if x < inner.x || x >= inner.x + inner.width || y < inner.y || y >= inner.y + inner.height {
        return None;
    }
    let index = y.saturating_sub(inner.y) as usize;
    (index < outline_len).then_some(index)
}

/// Calculates the right-side TOC overlay area.
pub fn outline_overlay_area(area: Rect, item_count: usize, hovered: bool) -> Option<Rect> {
    if area.width < 24 || area.height < 4 || item_count == 0 {
        return None;
    }
    let width = if hovered {
        area.width.clamp(20, 30).min(area.width.saturating_sub(4))
    } else {
        12.min(area.width.saturating_sub(4))
    };
    let wanted_height = if hovered { item_count as u16 + 2 } else { 4 };
    let height = wanted_height.clamp(4, area.height.saturating_sub(1));
    Some(Rect {
        x: area.x + area.width.saturating_sub(width + 2),
        y: area.y + 1,
        width,
        height,
    })
}

/// Returns the content area inside a TOC block.
fn outline_inner_area(area: Rect) -> Rect {
    Block::default()
        .borders(Borders::ALL)
        .border_type(BorderType::Rounded)
        .inner(area)
}

/// Renders the outline block chrome.
fn render_outline_block(area: Rect, buf: &mut Buffer) {
    let panel_style = Style::default().bg(PANEL_BG);
    Block::default()
        .title(" TOC ")
        .borders(Borders::ALL)
        .border_type(BorderType::Rounded)
        .border_style(Style::default().fg(BORDER_FG).bg(PANEL_BG))
        .style(panel_style)
        .render(area, buf);
}

/// Fills a rectangle with a style before overlay chrome is drawn.
fn fill_background(area: Rect, buf: &mut Buffer, style: Style) {
    for y in area.y..area.y + area.height {
        for x in area.x..area.x + area.width {
            if let Some(cell) = buf.cell_mut((x, y)) {
                cell.set_char(' ').set_style(style);
            }
        }
    }
}

/// Renders expanded outline entries.
fn render_expanded_entries(
    area: Rect,
    buf: &mut Buffer,
    outline: &[DocumentOutlineItem],
    hovered_entry: Option<usize>,
) {
    for (row, item) in outline.iter().take(area.height as usize).enumerate() {
        let prefix = "  ".repeat(item.level.min(3));
        let text = format!("{prefix}{}", item.title);
        let style = if hovered_entry == Some(row) {
            Style::default().fg(Color::White).bg(HOVER_BG)
        } else {
            Style::default().fg(TEXT_FG).bg(PANEL_BG)
        };
        buf.set_stringn(
            area.x,
            area.y + row as u16,
            text,
            area.width as usize,
            style,
        );
    }
}

/// Renders the compact TOC marker.
fn render_compact_marker(area: Rect, buf: &mut Buffer) {
    if area.is_empty() {
        return;
    }
    buf.set_stringn(
        area.x,
        area.y,
        "⠉⢙⣛⣛⣛⣛⣛⣛⣛⣛",
        area.width as usize,
        Style::default().fg(COMPACT_LINE_FG).bg(PANEL_BG),
    );
}