ratapp 0.4.0

A tiny framework to build multi-screen async applications with ratatui.
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
161
162
163
164
165

//! The main application loop and event handling.

use ratatui::crossterm::event::{self, Event};
use tokio::sync::{mpsc, watch};

use crate::{navigation::Navigator, screen::ScreenState};

/// The main application struct that runs the event loop and manages screens.
///
/// To create an instance of `App`, use the [`App::new()`] method with your
/// [`Screens`](crate::Screens)-derived type.
///
/// ```ignore
/// let mut app = App::<MyScreens>::new();
/// ```
///
/// Then, to run the application, call the asynchronous [`App::run()`] method:
///
/// ```ignore
/// let mut app = App::<MyScreens>::new();
///
/// app.run().await?;
/// ```
///
/// You can also create an `App` instance with a global application state using the
/// [`App::with_state()`] method:
///
/// ```ignore
/// let initial_state = MyAppState { /* initialize your state here */ };
/// let mut app = App::<MyScreens, MyAppState>::with_state(initial_state);
/// ```
///
/// To use application state within your screens, implement the
/// [`ScreenWithState`](crate::ScreenWithState) trait for your screens instead of the
/// [`Screen`](crate::Screen) trait. This allows your screens to access and modify the shared
/// application state.
pub struct App<S, T = ()>
where
    S: ScreenState<T>,
{
    renders: (watch::Sender<()>, watch::Receiver<()>),
    events: mpsc::UnboundedReceiver<Event>,
    screen: S,
    state: T,
}

impl<S> App<S, ()>
where
    S: ScreenState<()>,
{
    /// Creates a new `App` instance with the default screen without any application state.
    ///
    /// Returns:
    /// [`App`] - A new application instance.
    pub fn new() -> Self {
        let (events_tx, events_rx) = mpsc::unbounded_channel();

        tokio::task::spawn_blocking(move || {
            loop {
                if let Ok(event) = event::read()
                    && events_tx.send(event).is_err()
                {
                    break;
                }
            }
        });

        let (renders_tx, renders_rx) = watch::channel(());

        Self {
            renders: (renders_tx, renders_rx),
            events: events_rx,
            screen: S::default(),
            state: (),
        }
    }
}

impl<S, T> App<S, T>
where
    S: ScreenState<T>,
{
    /// Creates a new `App` instance with the default screen and provided application state.
    ///
    /// Parameters:
    /// * `state` - The initial application state.
    ///
    /// Returns:
    /// [`App`] - A new application instance.
    pub fn with_state(state: T) -> Self {
        let (events_tx, events_rx) = mpsc::unbounded_channel();

        tokio::task::spawn_blocking(move || {
            loop {
                if let Ok(event) = event::read()
                    && events_tx.send(event).is_err()
                {
                    break;
                }
            }
        });

        let (renders_tx, renders_rx) = watch::channel(());

        Self {
            renders: (renders_tx, renders_rx),
            events: events_rx,
            screen: S::default(),
            state,
        }
    }

    /// Runs the main application loop, handling events and screen rendering.
    ///
    /// Returns:
    /// `std::io::Result<()>` - Result of the application run.
    pub async fn run(&mut self) -> std::io::Result<()> {
        let mut terminal = ratatui::init();

        loop {
            terminal
                .draw(|frame| self.screen.draw(frame, &mut self.state))
                .inspect_err(|_| {
                    ratatui::restore();
                })?;

            tokio::select! {
                Ok(_) = self.renders.1.changed() => {},
                Some(event) = self.events.recv() => {
                    let navigator = Navigator::new(self.renders.0.clone());

                    self.screen.on_event(event, &navigator, &mut self.state).await;

                    let lock = navigator.inner.lock().await;

                    if lock.should_exit {
                        self.screen.on_exit(&mut self.state).await;
                        break;
                    }

                    if let Some(id) = lock.next_screen {
                        self.screen.on_exit(&mut self.state).await;
                        self.screen.navigate(&id);
                        self.screen.on_enter(&mut self.state).await;
                    }
                },
                _ = self.screen.rerender(&mut self.state) => {}
            }
        }

        ratatui::restore();

        Ok(())
    }
}

impl<S, T> Default for App<S, T>
where
    S: ScreenState<T>,
    T: Default,
{
    fn default() -> Self {
        Self::with_state(T::default())
    }
}