saorsa_core/
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 buffer;
65pub mod cell;
66pub mod color;
67pub mod compositor;
68pub mod cursor;
69pub mod error;
70pub mod event;
71pub mod focus;
72pub mod geometry;
73pub mod highlight;
74pub mod layout;
75pub mod overlay;
76pub mod reactive;
77pub mod render_context;
78pub mod renderer;
79pub mod segment;
80pub mod style;
81pub mod tcss;
82pub mod terminal;
83pub mod text;
84pub mod text_buffer;
85pub mod undo;
86pub mod viewport;
87pub mod widget;
88pub mod wrap;
89
90pub use buffer::{CellChange, ScreenBuffer};
91pub use cell::Cell;
92pub use color::Color;
93pub use compositor::{Compositor, CompositorError, CompositorRegion, Layer};
94pub use cursor::{CursorPosition, CursorState, Selection};
95pub use error::{Result, SaorsaCoreError};
96pub use event::{Event, KeyCode, KeyEvent, Modifiers, MouseEvent};
97pub use focus::{FocusManager, FocusState, WidgetId};
98pub use geometry::{Position, Rect, Size};
99pub use highlight::{HighlightSpan, Highlighter, NoHighlighter, SimpleKeywordHighlighter};
100pub use layout::{
101    Constraint, Direction, Dock, Layout, LayoutEngine, LayoutError, LayoutRect, OverflowBehavior,
102    ScrollManager, ScrollState,
103};
104pub use overlay::{OverlayConfig, OverlayId, OverlayPosition, Placement, ScreenStack};
105pub use reactive::{
106    Binding, BindingDirection, BindingExpression, BindingId, BindingScope, Computed, Effect,
107    OneWayBinding, PropertySink, ReactiveScope, Signal, TwoWayBinding, batch,
108};
109pub use render_context::RenderContext;
110pub use renderer::{DeltaBatch, Renderer, batch_changes, build_sgr_sequence};
111pub use segment::Segment;
112pub use style::Style;
113pub use terminal::{
114    CrosstermBackend, MultiplexerKind, Terminal, TerminalCapabilities, TerminalInfo, TerminalKind,
115    TestBackend, detect, detect_multiplexer, detect_terminal, merge_multiplexer_limits,
116    profile_for,
117};
118pub use text::{
119    TextConfig, expand_tabs, filter_control_chars, preprocess, string_display_width,
120    truncate_to_char_boundary, truncate_to_display_width,
121};
122pub use text_buffer::TextBuffer;
123pub use undo::{EditOperation, UndoStack};
124pub use viewport::Viewport;
125pub use widget::{
126    Alignment, BorderStyle, Checkbox, Collapsible, Column, Container, DataTable, DiffMode,
127    DiffView, DirectoryTree, EventResult, IndicatorStyle, Label, LoadingIndicator,
128    MarkdownRenderer, Modal, OptionList, ProgressBar, ProgressMode, RadioButton, RichLog,
129    SelectList, Sparkline, StaticWidget, Switch, Tab, TabBarPosition, Tabs, TextArea, Toast,
130    ToastPosition, Tooltip, Tree, TreeNode, Widget,
131};
132pub use wrap::{WrapLine, WrapResult, line_number_width, wrap_line, wrap_lines};
saorsa_core/lib.rs

saorsa_core/
lib.rs
