tuika 0.5.0

A composable terminal UI toolkit — flexbox layout, overlays, focus, and safe ratatui interoperability.
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
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

//! Modal dialog composition from existing Tuika primitives.

use crate::geometry::Padding;
use crate::overlay::{Extent, OverlaySpec};
use crate::scene::{Backdrop, SceneOverlay};
use crate::style::BorderStyle;
use crate::view::{Element, element};

use super::{Boxed, Flex, KeyHints};

/// Builder for an owned modal dialog layer.
///
/// The content and optional actions are ordinary [`Element`]s, so forms,
/// markdown, selectors, and custom views compose without dialog-specific
/// adapters. Persistent control state remains host-owned.
///
/// ![dialog demo](https://raw.githubusercontent.com/everruns/tuika/main/docs/demos/primitives.gif)
pub struct Dialog {
    title: String,
    content: Element,
    actions: Option<Element>,
    spec: OverlaySpec,
    border: BorderStyle,
    padding: Padding,
    clear: bool,
    dim: bool,
    owner: Option<String>,
}

impl Dialog {
    /// Create a centered dialog with a raised-surface background.
    pub fn new(title: impl Into<String>, content: Element) -> Self {
        Self {
            title: title.into(),
            content,
            actions: None,
            spec: OverlaySpec::centered(60, 60).min_size(24, 5).margin(1),
            border: BorderStyle::Rounded,
            padding: Padding::symmetric(1, 0),
            clear: true,
            dim: false,
            owner: None,
        }
    }

    /// Set an arbitrary actions/footer view.
    pub fn actions(mut self, actions: Element) -> Self {
        self.actions = Some(actions);
        self
    }

    /// Set the footer to compact `(key, action)` hints.
    pub fn key_hints<K, L>(self, hints: impl IntoIterator<Item = (K, L)>) -> Self
    where
        K: Into<String>,
        L: Into<String>,
    {
        self.actions(element(KeyHints::new(hints)))
    }

    /// Replace the complete overlay placement specification.
    pub fn placement(mut self, spec: OverlaySpec) -> Self {
        self.spec = spec;
        self
    }

    /// Set absolute dialog width and height.
    pub fn size(mut self, width: u16, height: u16) -> Self {
        self.spec.width = Extent::Cells(width);
        self.spec.height = Extent::Cells(height);
        self
    }

    /// Set minimum resolved dialog size.
    pub fn min_size(mut self, width: u16, height: u16) -> Self {
        self.spec = self.spec.min_size(width, height);
        self
    }

    /// Set maximum resolved dialog size.
    pub fn max_size(mut self, width: u16, height: u16) -> Self {
        self.spec = self.spec.max_size(width, height);
        self
    }

    /// Set the dialog border glyph style.
    pub fn border(mut self, border: BorderStyle) -> Self {
        self.border = border;
        self
    }

    /// Set padding between dialog chrome and content.
    pub fn padding(mut self, padding: Padding) -> Self {
        self.padding = padding;
        self
    }

    /// Dim all already-rendered layers behind the dialog.
    pub fn dim_backdrop(mut self, dim: bool) -> Self {
        self.dim = dim;
        self
    }

    /// Clear the overlay rectangle before painting (default true).
    pub fn clear(mut self, clear: bool) -> Self {
        self.clear = clear;
        self
    }

    /// Claim exclusive input ownership for this id while the dialog is topmost.
    pub fn focus_owner(mut self, id: impl Into<String>) -> Self {
        self.owner = Some(id.into());
        self
    }

    /// Finish the composition as an owned scene overlay.
    pub fn into_overlay(self) -> SceneOverlay {
        let mut body = Flex::column().grow(1, self.content);
        if let Some(actions) = self.actions {
            body = body.fixed(1, actions);
        }
        let panel = Boxed::new(element(body))
            .title(format!(" {} ", self.title))
            .border(self.border)
            .padding(self.padding);
        let mut overlay = SceneOverlay::new(element(panel), self.spec)
            .clear(self.clear)
            .backdrop(if self.dim {
                Backdrop::Dim
            } else {
                Backdrop::None
            });
        if let Some(owner) = self.owner {
            overlay = overlay.focus_owner(owner);
        }
        overlay
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::components::Text;
    use crate::scene::Scene;
    use crate::testing::{grid, render};
    use crate::{Theme, element};

    #[test]
    fn dialog_composes_title_content_and_hints() {
        let scene = Scene::new(element(Text::raw("base"))).dialog(
            Dialog::new("Confirm", element(Text::raw("Delete?")))
                .size(18, 5)
                .key_hints([("enter", "yes"), ("esc", "no")]),
        );
        let rendered = grid(&render(&scene, 20, 7, &Theme::default()));
        assert!(rendered.contains(" Confirm "));
        assert!(rendered.contains("Delete?"));
        assert!(rendered.contains("enter"));
    }
}