Crate termtui 

Radical TUI - Terminal User Interface Framework

A reactive terminal UI framework inspired by React’s virtual DOM architecture. Provides a declarative API for building interactive terminal applications.

Architecture Overview

    ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
    │  Elements   │────▶│    Node     │────▶│    VDom     │
    │   Factory   │     │    Tree     │     │   State     │
    └─────────────┘     └─────────────┘     └─────────────┘
           │                    │                    │
           │                    │                    │
           ▼                    ▼                    ▼
    ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
    │    Style    │     │    Diff     │────▶│   Render    │
    │   System    │     │   Engine    │     │   Engine    │
    └─────────────┘     └─────────────┘     └─────────────┘
                                                    │
                                                    ▼
                                           ┌─────────────┐
                                           │  Terminal   │
                                           │   Output    │
                                           └─────────────┘

Quick Start

use termtui::{Elements, ElementBuilder, Text, Node, Color, Direction, Spacing};

// Create UI elements using the Elements factory
let ui = Elements::div()
    .background(Color::Blue)
    .padding(Spacing::all(2))
    .children(vec![
        Text::new("Hello, TUI!").color(Color::White).into(),
        Elements::div()
            .direction(Direction::Horizontal)
            .children(vec![
                Text::new("Left").into(),
                Text::new("Right").into(),
            ])
            .into(),
    ])
    .into();

Key Components

• Node: Virtual representation of UI elements (Element trait objects or Text)
• Elements: Factory for creating concrete element types (Div, etc.)
• Element: Trait for element data access (props, children)
• ElementBuilder: Trait providing fluent builder API for elements
• VDom: Manages the virtual DOM state and updates
• Diff: Calculates minimal changes between UI states
• Render: Translates virtual nodes to terminal output
• App: Main application lifecycle and event loop
• Model: Type-safe init-view-update architecture for stateful models

Re-exports

pub use app::App;

pub use app::Context;

pub use app::Dispatcher;

pub use app::RenderConfig;

pub use app::StateMap;

pub use bounds::Rect;

pub use component::Action;

pub use component::Component;

pub use component::ComponentId;

pub use component::Message;

pub use component::State;

pub use components::TextInput;

pub use diff::Patch;

pub use diff::diff;

pub use key::Key;

pub use node::Div;

pub use node::Node;

pub use node::RichText;

pub use node::Text;

pub use node::TextSpan;

pub use render_tree::RenderNode;

pub use style::BorderEdges;

pub use style::BorderStyle;

pub use style::Color;

pub use style::Dimension;

pub use style::Direction;

pub use style::Overflow;

pub use style::Position;

pub use style::Spacing;

pub use style::Style;

pub use style::TextStyle;

pub use style::TextWrap;

pub use style::WrapMode;

pub use utils::wrap_text;

pub use vdom::VDom;

pub use vnode::VNode;

Modules

app

Application framework for building terminal UIs. Provides the main application lifecycle and event handling.

bounds

Bounds and rectangle operations for dirty region tracking. Provides types for tracking screen regions that need redrawing. Bounds and rectangle operations for dirty region tracking.

buffer

Double buffering and cell-level diffing for flicker-free rendering. Maintains screen state to enable precise, minimal updates. Double buffering and cell-level diffing for flicker-free rendering.

component

New component-based system (parallel implementation)

components

Reusable UI components for building forms and interfaces Provides pre-built components like TextInput, Button, etc. Reusable UI components for termtui

diff

Diffing algorithm for efficiently updating the UI. Compares old and new virtual DOM trees to generate minimal change patches. Virtual DOM diffing algorithm for efficient UI updates.

key

Key representation for keyboard input. Provides an enum for representing both characters and special keys. Key representation for keyboard input handling.

macros

Macro-based DSL for building TUI components Provides ergonomic macros for composing components with less boilerplate Macro-based DSL for building TUI components

node

Node types for component tree (includes div, text, rich_text)

prelude

Prelude module for convenient imports Prelude module for convenient imports.

render_tree

Rendering engine that converts virtual nodes into terminal output. Handles the actual drawing of elements to the screen. Render tree and layout engine for terminal UI.

style

Styling system for terminal UI components. Defines colors, spacing, borders, and other visual properties. Styling system for terminal UI models.

terminal

Optimized terminal renderer for applying cell updates. Minimizes escape sequences and I/O operations for best performance. Optimized terminal renderer that applies cell updates efficiently.

utils

Utilities for terminal rendering, Unicode width calculations, and text wrapping. Provides helpers for display width, text manipulation, and wrapping algorithms. Utility functions for terminal rendering and text manipulation.

vdom

Virtual DOM implementation for managing the UI state. Maintains the current UI tree and applies patches from the diff engine. Virtual DOM implementation for efficient UI updates.

vnode

Virtual node types for the VDOM

Macros

debug_log

Debug logging macro that only compiles in debug builds. Writes timestamped messages to /tmp/radical_debug.log

tui

Main macro for building TUI components with a declarative syntax