lv-tui 0.4.0

A reactive TUI framework for Rust
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

//! # lv-tui — A reactive TUI framework for Rust
//!
//! `lv-tui` is a retained-mode terminal UI framework built from first principles
//! for the character-cell grid. It provides a component tree, reactive state
//! management, CSS-like styling, event bubbling, focus management, and more.
//!
//! ## Quick start
//!
//! ```rust,no_run
//! use lv_tui::prelude::*;
//! use lv_tui::Component;
//!
//! #[derive(Component)]
//! struct Counter {
//!     #[reactive(paint, copy)]
//!     count: i32,
//! }
//!
//! impl Counter {
//!     fn new() -> Self { Self { count: 0 } }
//! }
//!
//! impl Component for Counter {
//!     fn render(&self, cx: &mut RenderCx) {
//!         cx.line(format!("count: {}", self.get_count()));
//!         cx.line("press + to increment, q to quit");
//!     }
//!
//!     fn event(&mut self, event: &Event, cx: &mut EventCx) {
//!         if event.is_key(Key::Char('+')) { self.set_count(self.get_count() + 1, cx); }
//!         if event.is_key(Key::Char('q')) { cx.quit(); }
//!     }
//! }
//!
//! fn main() -> lv_tui::Result<()> {
//!     App::new(Counter::new()).run()
//! }
//! ```
//!
//! ## Features
//!
//! - **Component tree** — compose UIs with [`Column`](widgets::Column),
//!   [`Row`](widgets::Row), [`Stack`](widgets::Stack),
//!   [`Block`](widgets::Block), [`Scroll`](widgets::Scroll),
//!   [`Overlay`](widgets::Overlay)
//! - **Reactive state** — `#[reactive(paint)]` auto-triggers repaint on change
//! - **Declarative events** — [`#[event_handlers]`](lv_tui_macros::event_handlers)
//!   macro generates `event()` from `on_focus`, `on_blur`, `on_key_*` handlers
//! - **Event bubbling** — Capture → Target → Bubble with `stop_propagation()`
//! - **Focus management** — Tab/Shift+Tab navigation with Focus/Blur events
//! - **CSS-like stylesheets** — type/class/id selectors with pseudo-classes
//!   (`:focus`, `:hover`, `:disabled`, `:focus-within`) and style inheritance
//! - **24-bit color** — `Color::Rgb(r,g,b)`, `Color::Indexed(i)`,
//!   `Color::hex("#ff8800")`, plus `"text".rgb(255,0,0)` via [`Stylize`](stylize::Stylize)
//! - **Unicode** — CJK/Emoji wide characters, text wrap, truncation, alignment
//! - **Timer API** — `set_timer(ms)`, `set_interval(ms)`, `cancel_timer(id)`
//! - **Cancellable workers** — `spawn_worker()` returns `WorkerId` for tracking
//! - **Headless testing** — [`Pilot`] driver with event injection and buffer inspection
//! - **Debug view** — press `d` to visualize component borders and labels
//!
//! ## Architecture
//!
//! ```text
//! App → Event Loop → Component → Reactive State → Dirty Mark
//!   → Layout → Render Buffer → Diff Flush → Terminal
//! ```
//!
//! The framework uses a **double-buffer** rendering strategy: components render
//! into a back buffer, then only the changed cells are flushed to the terminal
//! via diff operations.

pub mod app;
pub mod backend;
pub mod buffer;
pub mod clipboard;
pub mod component;
pub mod dirty;
pub mod event;
pub mod geom;
pub mod layout;
pub mod node;
pub mod pilot;
pub mod prelude;
pub mod render;
pub mod runtime;
pub mod style;
pub mod style_parser;
pub mod stylize;
pub mod testbuffer;
pub mod text;
pub mod widgets;

pub use lv_tui_macros::{event_handlers, Component};

/// Convenience alias for `std::result::Result<T, Error>`.
pub type Result<T> = std::result::Result<T, Error>;

/// Top-level error type for lv-tui.
#[derive(Debug, thiserror::Error)]
pub enum Error {
    /// Wraps a standard I/O error from the terminal or filesystem.
    #[error("IO error: {0}")]
    Io(#[from] std::io::Error),

    /// A terminal-specific error with a human-readable message.
    #[error("Terminal error: {0}")]
    Terminal(String),
}