tui/components/
component.rs

1use crossterm::event::{KeyEvent, KeyEventKind, MouseEvent};
2
3use crate::rendering::frame::Frame;
4use crate::rendering::render_context::{Size, ViewContext};
5
6#[doc = include_str!("../docs/event.md")]
7pub enum Event {
8    Key(KeyEvent),
9    Paste(String),
10    Mouse(MouseEvent),
11    Tick,
12    Resize(Size),
13}
14
15impl TryFrom<crossterm::event::Event> for Event {
16    type Error = ();
17
18    fn try_from(event: crossterm::event::Event) -> Result<Self, ()> {
19        match event {
20            crossterm::event::Event::Key(key) if matches!(key.kind, KeyEventKind::Press | KeyEventKind::Repeat) => {
21                Ok(Event::Key(key))
22            }
23            crossterm::event::Event::Paste(text) => Ok(Event::Paste(text)),
24            crossterm::event::Event::Mouse(mouse) => Ok(Event::Mouse(mouse)),
25            crossterm::event::Event::Resize(cols, rows) => Ok(Event::Resize((cols, rows).into())),
26            _ => Err(()),
27        }
28    }
29}
30
31#[doc = include_str!("../docs/component.md")]
32pub trait Component {
33    /// The message type emitted by this widget.
34    type Message;
35
36    /// Process an event and return the outcome.
37    ///
38    /// - `None` — event not recognized, propagate to parent
39    /// - `Some(vec![])` — event consumed, no messages
40    /// - `Some(vec![msg, ...])` — event consumed, emit messages
41    fn on_event(&mut self, _event: &Event) -> impl Future<Output = Option<Vec<Self::Message>>> {
42        async { None }
43    }
44
45    /// Render the current state to a frame.
46    fn render(&mut self, ctx: &ViewContext) -> Frame;
47}
48
49/// Merge two event outcomes. `None` (ignored) yields to the other.
50/// Messages are concatenated in order.
51pub fn merge<M>(a: Option<Vec<M>>, b: Option<Vec<M>>) -> Option<Vec<M>> {
52    match (a, b) {
53        (None, other) | (other, None) => other,
54        (Some(mut a), Some(b)) => {
55            a.extend(b);
56            Some(a)
57        }
58    }
59}
60
61/// Generic message type for picker components.
62pub enum PickerMessage<T> {
63    Close,
64    CloseAndPopChar,
65    CloseWithChar(char),
66    Confirm(T),
67    CharTyped(char),
68    PopChar,
69}
70
71#[cfg(test)]
72mod tests {
73    use super::*;
74    use crossterm::event::{KeyCode, KeyEventState, KeyModifiers};
75
76    #[test]
77    fn try_from_key_press_succeeds() {
78        let crossterm_event = crossterm::event::Event::Key(KeyEvent {
79            code: KeyCode::Char('a'),
80            modifiers: KeyModifiers::NONE,
81            kind: KeyEventKind::Press,
82            state: KeyEventState::NONE,
83        });
84        let event = Event::try_from(crossterm_event);
85        assert!(matches!(event, Ok(Event::Key(_))));
86    }
87
88    #[test]
89    fn try_from_key_release_fails() {
90        let crossterm_event = crossterm::event::Event::Key(KeyEvent {
91            code: KeyCode::Char('a'),
92            modifiers: KeyModifiers::NONE,
93            kind: KeyEventKind::Release,
94            state: KeyEventState::NONE,
95        });
96        assert!(Event::try_from(crossterm_event).is_err());
97    }
98
99    #[test]
100    fn try_from_paste_succeeds() {
101        let crossterm_event = crossterm::event::Event::Paste("hello".to_string());
102        let event = Event::try_from(crossterm_event);
103        assert!(matches!(event, Ok(Event::Paste(text)) if text == "hello"));
104    }
105
106    #[test]
107    fn try_from_resize_succeeds() {
108        let crossterm_event = crossterm::event::Event::Resize(80, 24);
109        let event = Event::try_from(crossterm_event);
110        assert!(matches!(event, Ok(Event::Resize(size)) if size.width == 80 && size.height == 24));
111    }
112
113    #[test]
114    fn try_from_focus_gained_fails() {
115        let crossterm_event = crossterm::event::Event::FocusGained;
116        assert!(Event::try_from(crossterm_event).is_err());
117    }
118}
tui/components/component.rs

tui/components/
component.rs
