saorsa_tui/lib.rs
1//! saorsa-core: A retained-mode, CSS-styled terminal UI framework.
2//!
3//! This crate provides the core rendering pipeline, layout engine,
4//! CSS styling system, and widget infrastructure for building
5//! rich terminal user interfaces.
6//!
7//! # Architecture Overview
8//!
9//! ```text
10//! ┌─────────────────────────────────────────────────────────────┐
11//! │ Application Layer │
12//! │ (Widget tree, CSS styles, reactive signals & bindings) │
13//! └─────────────────────────────────────────────────────────────┘
14//! │
15//! ▼
16//! ┌─────────────────────────────────────────────────────────────┐
17//! │ Layout Engine (Taffy) │
18//! │ TCSS → ComputedStyle → taffy::Style → computed rects │
19//! └─────────────────────────────────────────────────────────────┘
20//! │
21//! ▼
22//! ┌─────────────────────────────────────────────────────────────┐
23//! │ Widget Rendering System │
24//! │ Widget::render() → Vec<Segment> → Lines of styled text │
25//! └─────────────────────────────────────────────────────────────┘
26//! │
27//! ▼
28//! ┌─────────────────────────────────────────────────────────────┐
29//! │ Compositor (Layers, Z-ordering, Clipping) │
30//! │ Base layer + overlays → CompositorRegion → final buffer │
31//! └─────────────────────────────────────────────────────────────┘
32//! │
33//! ▼
34//! ┌─────────────────────────────────────────────────────────────┐
35//! │ Renderer (Differential, SGR optimization) │
36//! │ ScreenBuffer → DeltaBatch → optimized escape sequences │
37//! └─────────────────────────────────────────────────────────────┘
38//! │
39//! ▼
40//! ┌─────────────────────────────────────────────────────────────┐
41//! │ Terminal Backend (Crossterm) │
42//! │ Raw mode, cursor control, alternate screen, events │
43//! └─────────────────────────────────────────────────────────────┘
44//! ```
45//!
46//! ## Core Subsystems
47//!
48//! - **TCSS Parser**: CSS-like styling with variables, pseudo-classes, and themes
49//! - **Layout Engine**: Flexbox and grid layout via Taffy, scroll management
50//! - **Reactive System**: Signal-based state with computed values, effects, and bindings
51//! - **Compositor**: Layer-based rendering with z-ordering, clipping, and overlays
52//! - **Widget Library**: Rich set of data, text, and UI widgets (tables, trees, markdown, etc.)
53//! - **Renderer**: Double-buffered differential rendering with SGR optimization
54//!
55//! ## Key Types
56//!
57//! - `Segment`: Fundamental rendering unit (styled text + control flags)
58//! - `Cell`: Single terminal cell (grapheme cluster + style + display width)
59//! - `ScreenBuffer`: Double-buffered grid of cells with delta tracking
60//! - `Widget`: Trait for renderable UI components
61//! - `Signal<T>`: Reactive state container with automatic dependency tracking
62//! - `Compositor`: Manages layers and composition into final screen buffer
63
64pub mod app;
65pub mod buffer;
66pub mod cell;
67pub mod color;
68pub mod compositor;
69pub mod cursor;
70pub mod error;
71pub mod event;
72pub mod focus;
73pub mod geometry;
74pub mod highlight;
75pub mod layout;
76pub mod overlay;
77pub mod reactive;
78pub mod render_context;
79pub mod renderer;
80pub mod segment;
81pub mod style;
82pub mod tcss;
83pub mod terminal;
84pub mod text;
85pub mod text_buffer;
86pub mod undo;
87pub mod viewport;
88pub mod widget;
89pub mod wrap;
90
91#[cfg(test)]
92mod test_env;
93
94pub use buffer::{CellChange, ScreenBuffer};
95pub use cell::Cell;
96pub use color::Color;
97pub use compositor::{Compositor, CompositorError, CompositorRegion, Layer};
98pub use cursor::{CursorPosition, CursorState, Selection};
99pub use error::{Result, SaorsaTuiError};
100pub use event::{Event, KeyCode, KeyEvent, Modifiers, MouseEvent};
101pub use focus::{FocusManager, FocusState, WidgetId};
102pub use geometry::{Position, Rect, Size};
103pub use highlight::{HighlightSpan, Highlighter, NoHighlighter, SimpleKeywordHighlighter};
104pub use layout::{
105 Constraint, Direction, Dock, Layout, LayoutEngine, LayoutError, LayoutRect, OverflowBehavior,
106 ScrollManager, ScrollState,
107};
108pub use overlay::{OverlayConfig, OverlayId, OverlayPosition, Placement, ScreenStack};
109pub use reactive::{
110 Binding, BindingDirection, BindingExpression, BindingId, BindingScope, Computed, Effect,
111 OneWayBinding, PropertySink, ReactiveScope, Signal, TwoWayBinding, batch,
112};
113pub use render_context::RenderContext;
114pub use renderer::{DeltaBatch, Renderer, batch_changes, build_sgr_sequence};
115pub use segment::Segment;
116pub use style::Style;
117pub use terminal::{
118 CrosstermBackend, MultiplexerKind, Terminal, TerminalCapabilities, TerminalInfo, TerminalKind,
119 TestBackend, detect, detect_multiplexer, detect_terminal, merge_multiplexer_limits,
120 profile_for,
121};
122pub use text::{
123 TextConfig, expand_tabs, filter_control_chars, preprocess, string_display_width,
124 truncate_to_char_boundary, truncate_to_display_width,
125};
126pub use text_buffer::TextBuffer;
127pub use undo::{EditOperation, UndoStack};
128pub use viewport::Viewport;
129pub use widget::{
130 Alignment, BorderStyle, Checkbox, Collapsible, Column, Container, DataTable, DiffMode,
131 DiffView, DirectoryTree, EventResult, IndicatorStyle, Label, LoadingIndicator,
132 MarkdownRenderer, Modal, OptionList, ProgressBar, ProgressMode, RadioButton, RichLog,
133 SelectList, Sparkline, StaticWidget, Switch, Tab, TabBarPosition, Tabs, TextArea, Toast,
134 ToastPosition, Tooltip, Tree, TreeNode, Widget,
135};
136pub use wrap::{WrapLine, WrapResult, line_number_width, wrap_line, wrap_lines};