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
125
126
127
128
129
130
131
132
133
134
135

//! Stateless renderer wrapper for normalized documents.

use ratatui::{buffer::Buffer, layout::Rect};

use crate::widgets::document_viewer::{
    extensions::{render_outline, render_scrollbar, render_statusline},
    foundation::RenderedDocument,
    state::{DisplaySettings, ScrollState, SelectionState},
};

use super::render_document_lines;

/// Renders a normalized document with optional extensions.
#[derive(Debug, Clone)]
pub struct DocumentViewerWidget {
    document: RenderedDocument,
    display: DisplaySettings,
    selection: Option<SelectionState>,
    statusline: Option<String>,
    show_scrollbar: bool,
    outline_hovered: bool,
    outline_hovered_entry: Option<usize>,
}

impl DocumentViewerWidget {
    /// Creates a document viewer for a normalized document.
    pub fn new(document: RenderedDocument, display: DisplaySettings) -> Self {
        Self {
            document,
            display,
            selection: None,
            statusline: None,
            show_scrollbar: false,
            outline_hovered: false,
            outline_hovered_entry: None,
        }
    }

    /// Adds selection overlay state for this render.
    pub fn selection(mut self, selection: SelectionState) -> Self {
        self.selection = Some(selection);
        self
    }

    /// Adds a bottom statusline for this render.
    pub fn statusline(mut self, statusline: impl Into<String>) -> Self {
        self.statusline = Some(statusline.into());
        self
    }

    /// Toggles scrollbar rendering.
    pub fn show_scrollbar(mut self, show_scrollbar: bool) -> Self {
        self.show_scrollbar = show_scrollbar;
        self
    }

    /// Adds outline hover state for TOC overlay rendering.
    pub fn outline_hover(mut self, hovered: bool, entry: Option<usize>) -> Self {
        self.outline_hovered = hovered;
        self.outline_hovered_entry = entry;
        self
    }

    /// Renders the document into a buffer.
    pub fn render(&self, area: Rect, buf: &mut Buffer, scroll: &ScrollState) {
        let (content_area, statusline_area) = split_statusline(area, self.statusline.is_some());
        let outline_area = self.outline_area(content_area);
        let scrollbar_area = self.scrollbar_area(content_area);
        let line_area = if scrollbar_area.is_some() {
            Rect {
                width: content_area.width.saturating_sub(1),
                ..content_area
            }
        } else {
            content_area
        };

        render_document_lines(
            line_area,
            buf,
            &self.document.lines,
            scroll,
            &self.display,
            self.selection.as_ref(),
        );
        if let Some(area) = outline_area {
            render_outline(
                area,
                buf,
                &self.document.outline,
                self.outline_hovered,
                self.outline_hovered_entry,
            );
        }
        if let Some(area) = scrollbar_area {
            render_scrollbar(area, buf, scroll);
        }
        if let (Some(area), Some(statusline)) = (statusline_area, &self.statusline) {
            render_statusline(area, buf, statusline);
        }
    }

    /// Returns the overlay area used for outline/TOC rendering.
    fn outline_area(&self, area: Rect) -> Option<Rect> {
        (self.display.show_outline && !self.document.outline.is_empty()).then_some(area)
    }

    /// Returns the scrollbar area when enabled and useful.
    fn scrollbar_area(&self, area: Rect) -> Option<Rect> {
        (self.show_scrollbar && self.document.lines.len() > area.height as usize).then_some(Rect {
            x: area.x + area.width.saturating_sub(1),
            width: 1,
            ..area
        })
    }
}

/// Splits a bottom statusline area from the main area.
fn split_statusline(area: Rect, has_statusline: bool) -> (Rect, Option<Rect>) {
    if has_statusline && area.height > 1 {
        (
            Rect {
                height: area.height.saturating_sub(1),
                ..area
            },
            Some(Rect {
                y: area.y + area.height.saturating_sub(1),
                height: 1,
                ..area
            }),
        )
    } else {
        (area, None)
    }
}