envision 0.16.0

A ratatui framework for collaborative TUI development with headless testing support
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

//! Overlay trait definition.

use crate::component::RenderContext;
use crate::input::Event;

use super::OverlayAction;

/// A modal overlay that can intercept events and render on top of the main view.
///
/// Overlays own their transient UI state (search query, cursor position, scroll
/// offset) via `&mut self` on `handle_event`. The `Send` bound enables future
/// async compatibility.
///
/// # Example
///
/// ```rust
/// use envision::overlay::{Overlay, OverlayAction};
/// use envision::component::RenderContext;
/// use envision::input::{Event, Key};
///
/// struct ConfirmDialog {
///     message: String,
/// }
///
/// impl Overlay<String> for ConfirmDialog {
///     fn handle_event(&mut self, event: &Event) -> OverlayAction<String> {
///         if let Some(key) = event.as_key() {
///             match key.code {
///                 Key::Char('y') => OverlayAction::DismissWithMessage("confirmed".into()),
///                 Key::Char('n') | Key::Esc => OverlayAction::Dismiss,
///                 _ => OverlayAction::Consumed,
///             }
///         } else {
///             OverlayAction::Propagate
///         }
///     }
///
///     fn view(&self, ctx: &mut RenderContext<'_, '_>) {
///         // Render the confirmation dialog using ctx.frame, ctx.area, ctx.theme
///     }
/// }
/// ```
pub trait Overlay<M>: Send {
    /// Handle an input event.
    ///
    /// The overlay can mutate itself (e.g., update a search buffer).
    fn handle_event(&mut self, event: &Event) -> OverlayAction<M>;

    /// Render the overlay on top of the main view.
    fn view(&self, ctx: &mut RenderContext<'_, '_>);
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::component::RenderContext;
    use crate::input::Key;

    struct TestOverlay {
        consumed_count: u32,
    }

    impl Overlay<String> for TestOverlay {
        fn handle_event(&mut self, event: &Event) -> OverlayAction<String> {
            if let Some(key) = event.as_key() {
                match key.code {
                    Key::Esc => OverlayAction::Dismiss,
                    Key::Enter => OverlayAction::DismissWithMessage("confirmed".to_string()),
                    _ => {
                        self.consumed_count += 1;
                        OverlayAction::Consumed
                    }
                }
            } else {
                OverlayAction::Propagate
            }
        }

        fn view(&self, _ctx: &mut RenderContext<'_, '_>) {
            // no-op for testing
        }
    }

    #[test]
    fn test_overlay_handle_event_consumed() {
        let mut overlay = TestOverlay { consumed_count: 0 };
        let event = Event::char('a');

        let action = overlay.handle_event(&event);
        assert!(matches!(action, OverlayAction::Consumed));
        assert_eq!(overlay.consumed_count, 1);
    }

    #[test]
    fn test_overlay_handle_event_dismiss() {
        let mut overlay = TestOverlay { consumed_count: 0 };
        let event = Event::key(Key::Esc);

        let action = overlay.handle_event(&event);
        assert!(matches!(action, OverlayAction::Dismiss));
    }

    #[test]
    fn test_overlay_handle_event_dismiss_with_message() {
        let mut overlay = TestOverlay { consumed_count: 0 };
        let event = Event::key(Key::Enter);

        let action = overlay.handle_event(&event);
        assert!(matches!(action, OverlayAction::DismissWithMessage(ref s) if s == "confirmed"));
    }

    #[test]
    fn test_overlay_handle_event_propagate() {
        let mut overlay = TestOverlay { consumed_count: 0 };
        let event = Event::Resize(80, 24);

        let action = overlay.handle_event(&event);
        assert!(matches!(action, OverlayAction::Propagate));
    }
}