Crate lv_tui 

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

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, Row, Stack, Block, Scroll, Overlay
• Reactive state — #[reactive(paint)] auto-triggers repaint on change
• Declarative events — #[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
• 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

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.

Modules

app

backend

buffer

clipboard

System clipboard integration via OSC 52 escape sequences.

component

dirty

event

geom

layout

node

pilot

prelude

render

runtime

style

style_parser

stylize

testbuffer

Test utilities for asserting component render output.

text

widgets

Built-in widgets and layout containers.

Enums

Error

Top-level error type for lv-tui.

Type Aliases

Result

Convenience alias for std::result::Result<T, Error>.

Attribute Macros

event_handlers

Generates impl Component for Foo from an inherent impl block with on_* handler methods.

Derive Macros

Component