# rustom
A Rust library for building rich, stateful terminal user interfaces and dashboards.
rustom follows the immediate mode widget architecture common to modern Rust TUI libraries: widgets are cheap, disposable values that consume themselves when rendered into an in memory `Buffer`, the `Terminal` diffs the current buffer against the previous frame, and only the cells that actually changed get written to the real terminal. Rendering is backend agnostic through a `Backend` trait, with a `crossterm` implementation included.
## Features
- `Buffer` / `Cell`: the in memory grid every widget renders into.
- `Layout`: split a screen area into rows or columns using `Length`, `Percentage`, `Ratio`, `Min`, `Max`, and `Fill` constraints.
- `Style`, `Color`, `Modifier`: foreground and background colors plus text attributes like bold, italic, and underline.
- `Span`, `Line`, `Text`: composable styled text.
- Widgets: `Block`, `Paragraph` (with word wrap and scrolling), `List` (with selection and auto scroll), `Table` (with a header row and per column widths), `Gauge`, `LineGauge`, `Tabs`, `Sparkline`, `BarChart`, and `Scrollbar`.
- `Terminal`: double buffered, diff based rendering with a `crossterm` backend and `init` / `restore` helpers for raw mode and the alternate screen.
## Installation
```toml
[dependencies]
rustom = "0.1"
```
## Quick start
```rust,no_run
use std::io;
use rustom::layout::{Constraint, Direction, Layout};
use rustom::style::{Color, Style};
use rustom::widgets::{Block, Paragraph};
fn run() -> io::Result<()> {
let mut terminal = rustom::init()?;
terminal.draw(|frame| {
let chunks = Layout::default()
.direction(Direction::Vertical)
.constraints([Constraint::Length(3), Constraint::Fill(1)])
.split(frame.area());
frame.render_widget(Block::bordered().title("rustom"), chunks[0]);
let body = Paragraph::new("Hello from rustom.")
.style(Style::new().fg(Color::Cyan))
.block(Block::bordered());
frame.render_widget(body, chunks[1]);
})?;
rustom::restore()?;
Ok(())
}
```
Run the full demo, which wires up tabs, a list with a scrollbar, a table, a paragraph, a sparkline, a bar chart, a gauge, and a line gauge in a single event loop:
```sh
cargo run --example demo
```
Press `q` to quit, `j` / `k` or the arrow keys to move the list selection, and `Tab` to switch tabs.
## Design notes
- Widgets implement `Widget::render(self, area, buf)`, consuming themselves. Build a fresh widget from your application state every frame rather than mutating one in place.
- Widgets that need to remember something across frames (a selected list index, a scroll offset) implement `StatefulWidget` instead, and take a `&mut State` that you own and store alongside the rest of your application state.
- `Layout::split` uses a two pass greedy solver: fixed size constraints (`Length`, `Percentage`, `Ratio`, `Max`) claim their space first, then leftover space is divided among `Min` and `Fill` segments in proportion to their weights.
- `Chart` (axes and line/scatter datasets) and `Canvas` (arbitrary line drawing) are not implemented yet. Everything else in the widget list above is.
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
at your option.