Crate bubbletea_rs 

bubbletea-rs

A comprehensive Rust implementation of the Bubble Tea TUI framework. This library provides developers with the tools to build interactive terminal applications using the Model-View-Update (MVU) architecture pattern.

Features

• Model-View-Update Architecture: Clean separation of state, logic, and rendering
• Async Command System: Non-blocking operations with command-based side effects
• Terminal Interface Abstraction: Works with real terminals and test environments
• Comprehensive Event Handling: Keyboard, mouse, window resize, and focus events
• Memory Monitoring: Built-in memory usage tracking and leak detection
• Gradient Rendering: Rich color gradients for progress bars and visual elements
• Flexible Input Sources: Support for different input mechanisms and testing

Quick Start

use bubbletea_rs::{Model, Program, Msg, Cmd};

struct MyModel {
    counter: i32,
}

impl Model for MyModel {
    fn init() -> (Self, Option<Cmd>) {
        (Self { counter: 0 }, None)
    }

    fn update(&mut self, _msg: Msg) -> Option<Cmd> {
        None
    }

    fn view(&self) -> String {
        format!("Counter: {}", self.counter)
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let program = Program::<MyModel>::builder().build()?;
    program.run().await?;
    Ok(())
}

Architecture Overview

The library follows the Elm Architecture pattern:

1. Model: Your application state implementing the Model trait
2. Messages: Events that trigger state changes (keyboard, mouse, timers, etc.)
3. Update: Process messages and optionally issue commands
4. View: Render your model as a string for terminal display
5. Commands: Async operations that can produce future messages

Memory Safety

The framework includes built-in memory monitoring to help detect leaks and optimize performance. Use the MemoryMonitor to track allocations in your applications.

Testing

Testing is supported through the DummyTerminal which allows you to test your applications without requiring an actual terminal interface.

Re-exports

pub use command::batch;

pub use command::cancel_all_timers;

pub use command::cancel_timer;

pub use command::clear_screen;

pub use command::disable_bracketed_paste;

pub use command::disable_mouse;

pub use command::disable_report_focus;

pub use command::enable_bracketed_paste;

pub use command::enable_mouse_all_motion;

pub use command::enable_mouse_cell_motion;

pub use command::enable_report_focus;

pub use command::enter_alt_screen;

pub use command::every;

pub use command::every_with_id;

pub use command::exec_process;

pub use command::exit_alt_screen;

pub use command::hide_cursor;

pub use command::interrupt;

pub use command::printf;

pub use command::println;

pub use command::quit;

pub use command::sequence;

pub use command::set_window_title;

pub use command::show_cursor;

pub use command::suspend;

pub use command::tick;

pub use command::window_size;

pub use command::Batch;

pub use command::Cmd;

pub use error::Error;

pub use event::BatchMsgInternal;

pub use event::BlurMsg;

pub use event::CancelAllTimersMsg;

pub use event::CancelTimerMsg;

pub use event::ClearScreenMsg;

pub use event::DisableBracketedPasteMsg;

pub use event::DisableMouseMsg;

pub use event::DisableReportFocusMsg;

pub use event::EnableBracketedPasteMsg;

pub use event::EnableMouseAllMotionMsg;

pub use event::EnableMouseCellMotionMsg;

pub use event::EnableReportFocusMsg;

pub use event::EnterAltScreenMsg;

pub use event::EventReceiver;

pub use event::EventSender;

pub use event::ExitAltScreenMsg;

pub use event::FocusMsg;

pub use event::HideCursorMsg;

pub use event::InterruptMsg;

pub use event::KeyMsg;

pub use event::KillMsg;

pub use event::MouseMsg;

pub use event::Msg;

pub use event::PasteMsg;

pub use event::PrintMsg;

pub use event::PrintfMsg;

pub use event::QuitMsg;

pub use event::RequestWindowSizeMsg;

pub use event::ResumeMsg;

pub use event::SetWindowTitleMsg;

pub use event::ShowCursorMsg;

pub use event::SuspendMsg;

pub use event::WindowSizeMsg;

pub use gradient::charm_default_gradient;

pub use gradient::gradient_filled_segment;

pub use gradient::gradient_filled_segment_with_buffer;

pub use gradient::lerp_rgb;

pub use input::InputHandler;

pub use input::InputSource;

pub use memory::MemoryHealth;

pub use memory::MemoryMonitor;

pub use memory::MemorySnapshot;

pub use model::Model;

pub use program::MouseMotion;

pub use program::Program;

pub use program::ProgramBuilder;

pub use program::ProgramConfig;

pub use terminal::DummyTerminal;

pub use terminal::Terminal;

pub use terminal::TerminalInterface;

pub use logging::log_to_file;

Modules

command

Commands for async operations that produce messages. This module provides functions for creating and managing commands. Commands are asynchronous operations that can produce messages to update the model.

error

Error types and handling. Error types for bubbletea-rs.

event

Event types and message passing system. This module defines the various message types used in bubbletea-rs. Messages are events that trigger updates in your application’s model. They are typically sent by commands or the input handler.

gradient

Gradient rendering utilities for progress bars and color transitions.

input

Input handling abstraction for different sources. Input handling system for the Bubble Tea TUI framework.

logging

Logging utilities for debugging and monitoring. Logging utilities for bubbletea-rs applications.

memory

Memory monitoring and leak detection. Memory usage monitoring utilities.

model

The core Model trait defining application behavior. This module defines the core Model trait, which is central to the Model-View-Update (MVU) architecture used in bubbletea-rs applications. The Model trait provides a clear and consistent interface for managing application state, processing messages, and rendering the user interface.

prelude

Convenient re-exports of the most commonly used types.

program

Program runtime and builder for TUI applications. This module defines the Program struct and its associated ProgramBuilder, which are responsible for coordinating the entire bubbletea-rs application lifecycle. The Program sets up the terminal, handles input, executes commands, and renders the model’s view.

terminal

Terminal interface abstraction and implementations. Terminal management and abstraction for bubbletea-rs.