ratkit 0.2.15

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

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

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

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;
    };
    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) {
    Block::default()
        .title(" TOC ")
        .borders(Borders::ALL)
        .border_type(BorderType::Rounded)
        .border_style(Style::default().fg(Color::DarkGray))
        .render(area, buf);
}

/// 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::Black).bg(Color::Cyan)
        } else {
            Style::default().fg(Color::Gray)
        };
        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(Color::DarkGray),
    );
}