Ratatui: Events, Async & Application Architecture

use std::io;

use ratatui::{
    Frame,
    crossterm::event::{self, Event, KeyCode, KeyEventKind},
    layout::{Constraint, Layout},
    style::{Modifier, Style},
    widgets::{Block, List, ListItem, ListState, Paragraph},
};

const MAX_LOANS: usize = 2;

struct Book {
    title: &'static str,
    on_loan: bool,
}

struct Model {
    books: Vec<Book>,
    list: ListState,
    status: String,
    running: bool,
}

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum Message {
    Next,
    Previous,
    ToggleLoan,
    LimitReached,
    Quit,
}

fn update(model: &mut Model, message: Message) -> Option<Message> {
    match message {
        Message::Next => model.list.select_next(),
        Message::Previous => model.list.select_previous(),
        Message::ToggleLoan => {
            let index = model.list.selected()?;
            let loans = model.books.iter().filter(|b| b.on_loan).count();
            if !model.books[index].on_loan && loans >= MAX_LOANS {
                return Some(Message::LimitReached);
            }
            let book = &mut model.books[index];
            book.on_loan = !book.on_loan;
            model.status = format!("{} is now {}", book.title, if book.on_loan { "on loan" } else { "on the shelf" });
        }
        Message::LimitReached => model.status = format!("A member can borrow at most {MAX_LOANS} books"),
        Message::Quit => model.running = false,
    }
    None
}

fn view(model: &mut Model, frame: &mut Frame) {
    let [main, status] = Layout::vertical([Constraint::Fill(1), Constraint::Length(1)]).areas(frame.area());
    let items: Vec<ListItem> = model
        .books
        .iter()
        .map(|b| ListItem::new(format!("[{}] {}", if b.on_loan { "x" } else { " " }, b.title)))
        .collect();
    let list = List::new(items)
        .block(Block::bordered().title("shelf"))
        .highlight_style(Style::new().add_modifier(Modifier::REVERSED));
    frame.render_stateful_widget(list, main, &mut model.list);
    frame.render_widget(Paragraph::new(model.status.as_str()), status);
}

fn to_message(event: Event) -> Option<Message> {
    match event {
        Event::Key(key) if key.kind == KeyEventKind::Press => match key.code {
            KeyCode::Down | KeyCode::Char('j') => Some(Message::Next),
            KeyCode::Up | KeyCode::Char('k') => Some(Message::Previous),
            KeyCode::Enter => Some(Message::ToggleLoan),
            KeyCode::Char('q') | KeyCode::Esc => Some(Message::Quit),
            _ => None,
        },
        _ => None,
    }
}

fn main() -> io::Result<()> {
    let mut model = Model {
        books: vec![
            Book { title: "The Rust Programming Language", on_loan: false },
            Book { title: "Programming Pearls", on_loan: false },
            Book { title: "The Pragmatic Programmer", on_loan: false },
        ],
        list: ListState::default().with_selected(Some(0)),
        status: String::new(),
        running: true,
    };
    ratatui::run(|terminal| {
        while model.running {
            terminal.draw(|frame| view(&mut model, frame))?;
            let mut message = to_message(event::read()?);
            while let Some(current) = message {
                message = update(&mut model, current);
            }
        }
        Ok(())
    })
}

use ratatui::{Frame, crossterm::event::KeyEvent, layout::Rect};

/// What a component asks the application to do after handling something.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Action {
    Quit,
    Tick,
    Render,
    FocusNext,
    Search(String),
    LoanBook(usize),
    LoanFinished { index: usize, ok: bool },
    Noop,
}

pub trait Component {
    /// Called once, before the first frame.
    fn init(&mut self) {}
    /// Translate a key press into an action; components that do not care return Action::Noop.
    fn handle_key_event(&mut self, _key: KeyEvent) -> Action {
        Action::Noop
    }
    /// Apply an action to this component's private state; may produce a follow-up action.
    fn update(&mut self, _action: &Action) -> Option<Action> {
        None
    }
    /// Draw into the rectangle the parent layout assigned.
    fn render(&mut self, frame: &mut Frame, area: Rect);
}

struct BookList { /* books: Vec<Book>, state: ListState */ }
struct DetailsPane { /* selected: Option<usize> */ }
struct SearchBox { /* text: String, focused: bool */ }

struct Home {
    list: BookList,
    details: DetailsPane,
    search: SearchBox,
}

enum Action {
    Select(usize),
    LoanRequested(usize),
    LoanConfirmed(usize),
}

struct CatalogueStore {
    books: Vec<Book>,
    selected: Option<usize>,
}

impl CatalogueStore {
    fn update(&mut self, action: &Action) {
        match action {
            Action::Select(i) => self.selected = Some(*i),
            Action::LoanConfirmed(i) => self.books[*i].on_loan = true,
            Action::LoanRequested(_) => {}
        }
    }
}

struct Dispatcher {
    catalogue: CatalogueStore,
    // further stores: loans, settings, search results ...
}

impl Dispatcher {
    fn dispatch(&mut self, action: Action) {
        // The dispatcher has no logic of its own: every store sees every action.
        self.catalogue.update(&action);
    }
}

[package]
name = "shelf-tui-async"
version = "0.1.0"
edition = "2024"

[dependencies]
color-eyre = "0.6"
crossterm = { version = "0.29", features = ["event-stream"] }
futures = "0.3"
ratatui = "0.30"
tokio = { version = "1", features = ["macros", "rt-multi-thread", "time", "sync"] }

use std::time::Duration;

use crossterm::event::{Event as CrosstermEvent, EventStream, KeyEvent, KeyEventKind};
use futures::StreamExt;
use tokio::{
    sync::mpsc,
    time::{MissedTickBehavior, interval},
};

#[derive(Debug)]
pub enum Event {
    Tick,
    Render,
    Key(KeyEvent),
    Resize,
    Closed,
}

pub fn spawn_event_task(tick_rate: f64, frame_rate: f64) -> mpsc::UnboundedReceiver<Event> {
    let (tx, rx) = mpsc::unbounded_channel();
    tokio::spawn(async move {
        let mut reader = EventStream::new();
        let mut ticks = interval(Duration::from_secs_f64(1.0 / tick_rate));
        let mut frames = interval(Duration::from_secs_f64(1.0 / frame_rate));
        frames.set_missed_tick_behavior(MissedTickBehavior::Skip);

        loop {
            let event = tokio::select! {
                _ = ticks.tick() => Some(Event::Tick),
                _ = frames.tick() => Some(Event::Render),
                next = reader.next() => match next {
                    // Windows also sends Release events: forward presses only.
                    Some(Ok(CrosstermEvent::Key(key))) if key.kind == KeyEventKind::Press => Some(Event::Key(key)),
                    Some(Ok(CrosstermEvent::Resize(_, _))) => Some(Event::Resize),
                    Some(Ok(_)) => None,
                    Some(Err(_)) | None => Some(Event::Closed),
                },
            };
            let Some(event) = event else { continue };
            let closed = matches!(event, Event::Closed);
            // A failed send means the receiver was dropped: the application is shutting down.
            if tx.send(event).is_err() || closed {
                break;
            }
        }
    });
    rx
}

mod events; // the listing from the previous section, in src/events.rs

use std::time::Duration;

use color_eyre::Result;
use crossterm::event::{KeyCode, KeyEvent, KeyModifiers};
use ratatui::{
    DefaultTerminal, Frame,
    layout::{Constraint, Layout},
    style::{Modifier, Style},
    widgets::{Block, List, ListItem, ListState, Paragraph},
};
use tokio::sync::mpsc::{self, UnboundedSender};

use events::{Event, spawn_event_task};

#[derive(Debug)]
enum Action {
    Quit,
    Tick,
    Render,
    Next,
    Previous,
    RequestLoan,
    LoanFinished { index: usize, ok: bool },
}

struct Book {
    title: &'static str,
    on_loan: bool,
    pending: bool,
}

struct App {
    books: Vec<Book>,
    list: ListState,
    status: String,
    ticks: u64,
    should_quit: bool,
    action_tx: UnboundedSender<Action>,
}

impl App {
    fn handle_event(&self, event: Event) -> Option<Action> {
        match event {
            Event::Tick => Some(Action::Tick),
            Event::Render | Event::Resize => Some(Action::Render),
            Event::Closed => Some(Action::Quit),
            Event::Key(key) => self.handle_key(key),
        }
    }

    fn handle_key(&self, key: KeyEvent) -> Option<Action> {
        match key.code {
            KeyCode::Char('q') | KeyCode::Esc => Some(Action::Quit),
            // Raw mode: Ctrl+C is a key event, not a signal.
            KeyCode::Char('c') if key.modifiers.contains(KeyModifiers::CONTROL) => Some(Action::Quit),
            KeyCode::Down | KeyCode::Char('j') => Some(Action::Next),
            KeyCode::Up | KeyCode::Char('k') => Some(Action::Previous),
            KeyCode::Enter => Some(Action::RequestLoan),
            _ => None,
        }
    }

    fn update(&mut self, action: Action) {
        match action {
            Action::Quit => self.should_quit = true,
            Action::Tick => self.ticks += 1,
            Action::Render => {} // drawn by the main loop
            Action::Next => self.list.select_next(),
            Action::Previous => self.list.select_previous(),
            Action::RequestLoan => {
                let Some(index) = self.list.selected() else { return };
                if self.books[index].pending {
                    return;
                }
                self.books[index].pending = true;
                self.status = format!("Asking shelfd about \"{}\"", self.books[index].title);
                let tx = self.action_tx.clone();
                // Background work reports back through the same channel as the keyboard.
                tokio::spawn(async move {
                    tokio::time::sleep(Duration::from_millis(600)).await; // stands in for the IPC call
                    let _ = tx.send(Action::LoanFinished { index, ok: true });
                });
            }
            Action::LoanFinished { index, ok } => {
                let book = &mut self.books[index];
                book.pending = false;
                if ok {
                    book.on_loan = !book.on_loan;
                }
                self.status = format!("{}: {}", book.title, if book.on_loan { "on loan" } else { "on the shelf" });
            }
        }
    }

    fn view(&mut self, frame: &mut Frame) {
        let [main, status] = Layout::vertical([Constraint::Fill(1), Constraint::Length(1)]).areas(frame.area());
        let items: Vec<ListItem> = self
            .books
            .iter()
            .map(|b| {
                let mark = if b.pending { "..." } else if b.on_loan { "[x]" } else { "[ ]" };
                ListItem::new(format!("{mark} {}", b.title))
            })
            .collect();
        let list = List::new(items)
            .block(Block::bordered().title("shelf"))
            .highlight_style(Style::new().add_modifier(Modifier::REVERSED));
        frame.render_stateful_widget(list, main, &mut self.list);
        frame.render_widget(Paragraph::new(format!("{} (tick {})", self.status, self.ticks)), status);
    }

    async fn run(&mut self, terminal: &mut DefaultTerminal, mut actions: mpsc::UnboundedReceiver<Action>) -> Result<()> {
        let mut events = spawn_event_task(4.0, 30.0);
        while !self.should_quit {
            tokio::select! {
                Some(event) = events.recv() => {
                    if let Some(action) = self.handle_event(event) {
                        let _ = self.action_tx.send(action);
                    }
                }
                Some(action) = actions.recv() => match action {
                    Action::Render => {
                        terminal.draw(|frame| self.view(frame))?;
                    }
                    other => self.update(other),
                },
                else => break,
            }
        }
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<()> {
    color_eyre::install()?; // install error and panic reporting before ratatui::init, see "Panic and error hooks"
    let (action_tx, action_rx) = mpsc::unbounded_channel();
    let mut app = App {
        books: vec![
            Book { title: "The Rust Programming Language", on_loan: false, pending: false },
            Book { title: "Programming Pearls", on_loan: true, pending: false },
            Book { title: "The Pragmatic Programmer", on_loan: false, pending: false },
        ],
        list: ListState::default().with_selected(Some(0)),
        status: String::from("j/k move, Enter toggles loan, q quits"),
        ticks: 0,
        should_quit: false,
        action_tx,
    };
    let mut terminal = ratatui::init();
    let result = app.run(&mut terminal, action_rx).await;
    ratatui::restore();
    result
}

[dependencies]
crossterm = "0.28"
ratatui = { version = "0.30", default-features = false }
ratatui-crossterm = { version = "0.1", default-features = false, features = ["crossterm_0_28"] }