lv-tui 0.3.0

//! # 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
//! - **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 style inheritance
//! - **Unicode** — CJK/Emoji wide characters, text wrap, truncation, alignment
//! - **Async tasks** — `cx.spawn()` for background work with TaskComplete events
//! - **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 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::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),
}