ratapp 0.3.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

//! 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.
///
/// ```
/// let mut app = App::<MyScreens>::new();
/// ```
///
/// Then, to run the application, call the asynchronous [`App::run()`] method:
///
/// ```
/// let mut app = App::<MyScreens>::new();
///
/// app.run().await?;
/// ```
pub struct App<S>
where
    S: ScreenState,
{
    renders: (watch::Sender<()>, watch::Receiver<()>),
    events: mpsc::UnboundedReceiver<Event>,
    screen: S,
}

impl<S> App<S>
where
    S: ScreenState,
{
    /// Creates a new `App` instance with the default screen.
    /// 
    /// 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(),
        }
    }

    /// 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))
                .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).await;

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

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

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

        ratatui::restore();

        Ok(())
    }
}

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