lv_tui/
lib.rs

1//! # lv-tui — A reactive TUI framework for Rust
2//!
3//! `lv-tui` is a retained-mode terminal UI framework built from first principles
4//! for the character-cell grid. It provides a component tree, reactive state
5//! management, CSS-like styling, event bubbling, focus management, and more.
6//!
7//! ## Quick start
8//!
9//! ```rust,no_run
10//! use lv_tui::prelude::*;
11//! use lv_tui::Component;
12//!
13//! #[derive(Component)]
14//! struct Counter {
15//!     #[reactive(paint, copy)]
16//!     count: i32,
17//! }
18//!
19//! impl Counter {
20//!     fn new() -> Self { Self { count: 0 } }
21//! }
22//!
23//! impl Component for Counter {
24//!     fn render(&self, cx: &mut RenderCx) {
25//!         cx.line(format!("count: {}", self.get_count()));
26//!         cx.line("press + to increment, q to quit");
27//!     }
28//!
29//!     fn event(&mut self, event: &Event, cx: &mut EventCx) {
30//!         if event.is_key(Key::Char('+')) { self.set_count(self.get_count() + 1, cx); }
31//!         if event.is_key(Key::Char('q')) { cx.quit(); }
32//!     }
33//! }
34//!
35//! fn main() -> lv_tui::Result<()> {
36//!     App::new(Counter::new()).run()
37//! }
38//! ```
39//!
40//! ## Features
41//!
42//! - **Component tree** — compose UIs with [`Column`](widgets::Column),
43//!   [`Row`](widgets::Row), [`Stack`](widgets::Stack),
44//!   [`Block`](widgets::Block), [`Scroll`](widgets::Scroll),
45//!   [`Overlay`](widgets::Overlay)
46//! - **Reactive state** — `#[reactive(paint)]` auto-triggers repaint on change
47//! - **Declarative events** — [`#[event_handlers]`](lv_tui_macros::event_handlers)
48//!   macro generates `event()` from `on_focus`, `on_blur`, `on_key_*` handlers
49//! - **Event bubbling** — Capture → Target → Bubble with `stop_propagation()`
50//! - **Focus management** — Tab/Shift+Tab navigation with Focus/Blur events
51//! - **CSS-like stylesheets** — type/class/id selectors with pseudo-classes
52//!   (`:focus`, `:hover`, `:disabled`, `:focus-within`) and style inheritance
53//! - **24-bit color** — `Color::Rgb(r,g,b)`, `Color::Indexed(i)`,
54//!   `Color::hex("#ff8800")`, plus `"text".rgb(255,0,0)` via [`Stylize`](stylize::Stylize)
55//! - **Unicode** — CJK/Emoji wide characters, text wrap, truncation, alignment
56//! - **Timer API** — `set_timer(ms)`, `set_interval(ms)`, `cancel_timer(id)`
57//! - **Cancellable workers** — `spawn_worker()` returns `WorkerId` for tracking
58//! - **Headless testing** — [`Pilot`] driver with event injection and buffer inspection
59//! - **Debug view** — press `d` to visualize component borders and labels
60//!
61//! ## Architecture
62//!
63//! ```text
64//! App → Event Loop → Component → Reactive State → Dirty Mark
65//!   → Layout → Render Buffer → Diff Flush → Terminal
66//! ```
67//!
68//! The framework uses a **double-buffer** rendering strategy: components render
69//! into a back buffer, then only the changed cells are flushed to the terminal
70//! via diff operations.
71
72pub mod app;
73pub mod backend;
74pub mod buffer;
75pub mod clipboard;
76pub mod component;
77pub mod dirty;
78pub mod event;
79pub mod geom;
80pub mod layout;
81pub mod node;
82pub mod pilot;
83pub mod prelude;
84pub mod render;
85pub mod runtime;
86pub mod style;
87pub mod style_parser;
88pub mod stylize;
89pub mod testbuffer;
90pub mod text;
91pub mod widgets;
92
93pub use lv_tui_macros::{event_handlers, Component};
94
95/// Convenience alias for `std::result::Result<T, Error>`.
96pub type Result<T> = std::result::Result<T, Error>;
97
98/// Top-level error type for lv-tui.
99#[derive(Debug, thiserror::Error)]
100pub enum Error {
101    /// Wraps a standard I/O error from the terminal or filesystem.
102    #[error("IO error: {0}")]
103    Io(#[from] std::io::Error),
104
105    /// A terminal-specific error with a human-readable message.
106    #[error("Terminal error: {0}")]
107    Terminal(String),
108}
lv_tui/lib.rs

lv_tui/
lib.rs
