Using cascivo-tui

cascivo-tui is the cascivo design system for the terminal: a small widget toolkit on ratatui. You describe a screen as a tree of nodes styled with utility class strings ("col gap-1 p-1 border rounded text-accent"), and the crate lays it out and paints it with one of twelve cascivo themes. Apps follow one pattern: state, a pure view, and update for messages. Class strings are validated, so a typo is an error with a suggestion, not a silent no-op.

MSRV: Rust 1.88 (ratatui 0.30 requires it; the workspace default is lower).

Quickstart

[dependencies]
cascivo-tui = "0.1"

A counter. + adds one, q quits, ctrl+c always quits.

use cascivo_tui::prelude::*;

#[derive(Clone)]
enum Msg {
    Inc,
    Quit,
}

struct Counter(i32);

impl App for Counter {
    type Msg = Msg;

    fn update(&mut self, msg: Msg) -> Cmd<Msg> {
        match msg {
            Msg::Inc => {
                self.0 += 1;
                Cmd::none()
            }
            Msg::Quit => Cmd::Quit,
        }
    }

    fn view(&self) -> Node<Msg> {
        col("p-1", [text(format!("count: {}", self.0)).into()])
    }

    fn keys(&self) -> Keymap<Msg> {
        Keymap::new().bind("+", "add", Msg::Inc).bind("q", "quit", Msg::Quit)
    }
}

fn main() -> Result<(), TuiError> {
    run(Counter(0))
}

The full reference app is crates/cascivo-tui/examples/dashboard.rs (logic in examples/support/mod.rs): three tabs, a table, a log list, a restart modal, toasts and live theme switching. Run it with cargo run -p cascivo-tui --example dashboard.

Mental model

use cascivo_tui::prelude::*;

// The one-line row keeps one line; only the body grows. Wrapped text keeps its tail.
let n: Node = col(
    "",
    [
        text("tabs").into(),
        row("gap-1", [text("a").into(), text("b").into()]),
        col("grow border", [text("one two three four").into()]),
    ],
);
let screen = render_to_string(&n, 8, 6).unwrap();
assert_eq!(screen.lines().nth(1), Some("a b"));
assert_eq!(screen.lines().nth(2), Some("┌──────┐"));
let wrapped: Node = col("", [text("one two three four").into(), text("x").into()]);
assert_eq!(render_to_string(&wrapped, 6, 6).unwrap(), "one\ntwo\nthree\nfour\nx");

Class table

N is an integer 0..=64 (grow-N: 0..=16). row and col are node kinds chosen by the builder, not classes. Conflicting tokens resolve last-wins (w-4 w-8 is width 8); text modifiers (bold italic) and border sides (border-t border-l) accumulate. Role names use the snake names below: text-accent_fg, bg-surface2, border-border_strong. This table is checked against cascivo_tui::class::VOCABULARY by tests/docs.rs.

ClassMeaning
gap-NCells between children.
p-N px-N py-N pt-N pr-N pb-N pl-NPadding in cells: all, horizontal, vertical, top, right, bottom, left.
w-N h-NFixed width / height in cells.
w-full h-fullFill the parent along that axis.
w-1/2 w-1/3 w-2/3 w-1/4 w-3/4Fraction of the parent width.
h-1/2 h-1/3 h-2/3 h-1/4 h-3/4Fraction of the parent height.
min-w-N min-h-N max-w-N max-h-NLower / upper bounds in cells.
grow grow-NShare leftover main-axis space (grow is grow-1).
shrink-0Keep the intrinsic size.
justify-start justify-center justify-end justify-between justify-around justify-evenlyMain-axis distribution (default justify-start).
items-start items-center items-end items-stretchCross-axis alignment (default items-stretch).
borderBorder on all sides.
border-noneClear all border sides.
border-t border-r border-b border-l border-x border-yIndividual sides; they accumulate.
roundedRounded corner style; combine with border.
border-double border-thick border-plainBorder line style.
border-bg border-surface border-surface2 border-border border-border_strong border-fg border-muted border-accent border-accent_fg border-success border-warning border-danger border-info border-focus border-selectionBorder colour from a theme role.
text-fg text-muted text-accent text-accent_fg text-success text-warning text-danger text-infoText colour from a theme role.
bg-bg bg-surface bg-surface2 bg-accent bg-selection bg-success bg-warning bg-danger bg-infoBackground colour from a theme role.
bold italic underline strike dim reverseText modifiers; they accumulate.
text-left text-center text-rightText alignment.
truncate wrap nowrapOverflow handling for text.
scroll-y clipScroll or clip overflowing content vertically.
hiddenSkip the node entirely.

Variants prefix any colour, modifier or layout token: focus:, selected:, disabled: (state variants, colour and modifier tokens only) and narrow: (frames under 80 columns). Example: "bg-surface focus:bg-accent focus:text-accent_fg narrow:p-0".

Theme roles: bg, surface, surface2, border, border_strong, fg, muted, accent, accent_fg, success, warning, danger, info, focus, selection.

Widgets

All widgets are in cascivo_tui::prelude::* (and the crate root). Widgets that take input join the focus ring only once they have an .id("..."). Builders that return a struct (list, table, input) convert into a node with .into() or by ending the chain with .id(..).

text, col, row, spacer

use cascivo_tui::prelude::*;

let n: Node = col(
    "gap-1 p-1",
    [
        text("Revenue").bold().into(),
        row("gap-2", [text("left").into(), spacer(), text("right").muted().into()]),
    ],
);
assert!(render_to_string(&n, 20, 4).unwrap().contains("Revenue"));

col(class, children), row(class, children), spacer(), text(s) with .class(..), .bold(), .muted().

heading

heading(s: impl Into<String>) -> Node<M>: bold, accent-coloured text.

use cascivo_tui::prelude::*;

let n: Node = heading("Title");
assert_eq!(n.classes(), "bold text-accent");

card

card(title: &str, class: &str, children: impl Into<Vec<Node<M>>>) -> Node<M>: a rounded, bordered surface with the title on the top border.

use cascivo_tui::prelude::*;

let n: Node = card("Stats", "", [text("ok").into()]);
assert_eq!(n.border_title(), Some("Stats"));

button

button(label: &str, on_press: M) -> Node<M> where M: Clone + 'static. Enter or Space while focused emits a clone of on_press. Needs an id to be focusable.

use cascivo_tui::prelude::*;

let n: Node<&str> = button("Save", "save").id("save");
assert!(n.is_focusable());
assert_eq!(render_to_string(&n, 10, 1).unwrap(), " Save");

input

input(value: &str, placeholder: &str, on_change: impl Fn(String) -> M) -> Input<M>. Builder methods: .on_submit(msg), .cursor(&Cursor), .class(..), .id(..). Typing, Backspace, Delete, Left, Right, Home and End all emit on_change(new_value); store whatever it gives you. Keep one Cursor in the app and pass it on every build, otherwise the cursor stays at the end. The input has no built-in padding: add .class("px-1") for an inset, so a label and gap-1 read Name: Ada.

use cascivo_tui::prelude::*;

let n: Node<String> = input("héllo", "name", |s| s).id("name");
assert_eq!(render_to_string(&n, 10, 1).unwrap(), "héllo");

let cursor = Cursor::default();
cursor.set(2);
assert_eq!(cursor.get(), Some(2));

list

list(items: Vec<String>, selected: usize, on_select: impl Fn(usize) -> M) -> List<M>. j/k/ Down/Up emit on_select(index) and clamp at the ends. Builder: .on_activate(Fn(usize) -> M) for Enter, .scroll(&Scroll), .class(..), .id(..). Keep one Scroll in the app.

use cascivo_tui::prelude::*;

let n: Node<usize> = list(vec!["a".into(), "b".into(), "c".into()], 1, |i| i).id("files");
assert_eq!(render_to_string(&n, 6, 2).unwrap(), "  a\n› b");

table

table(header: &[&str], rows: Vec<Vec<String>>, widths: &[Col], selected: usize, on_select: impl Fn(usize) -> M) -> Table<M>. Col::Grow(n) shares space, Col::Fixed(n) is n cells; a column with no Col is Grow(1). The header is sticky and only the body scrolls. Same builder as list.

use cascivo_tui::prelude::*;
use cascivo_tui::widgets::Col;

let n: Node<usize> = table(
    &["Name", "Qty"],
    vec![vec!["apple".into(), "3".into()]],
    &[Col::Grow(1), Col::Fixed(3)],
    0,
    |i| i,
)
.id("t");
assert_eq!(render_to_string(&n, 10, 2).unwrap(), "Name   Qty\napple  3");

tabs

tabs(titles: &[&str], active: usize, on_change: impl Fn(usize) -> M) -> Node<M>. Left/Right move and clamp; 1-9 jump. The app decides which body to show from active.

use cascivo_tui::prelude::*;

let n: Node<usize> = tabs(&["One", "Two"], 1, |i| i).id("tabs");
assert_eq!(render_to_string(&n, 12, 1).unwrap(), " One   Two");

progress

progress(ratio: f64, label: &str) -> Node<M>: ratio clamped to 0..=1.

use cascivo_tui::prelude::*;

let n: Node = progress(0.5, "cpu");
assert_eq!(render_to_string(&n, 14, 1).unwrap(), "cpu 50% ███░░░");

sparkline

sparkline(data: &[u64]) -> Node<M>: scaled to the largest value; shows the latest values when too wide.

use cascivo_tui::prelude::*;

let n: Node = sparkline(&[0, 4, 8]);
assert_eq!(render_to_string(&n, 5, 1).unwrap(), "▁▄█");

statusbar

statusbar(left: impl Into<String>, right: impl Into<String>) -> Node<M>: one row on the raised surface; left truncates, right stays whole.

use cascivo_tui::prelude::*;

let n: Node = statusbar("ready", "q quit");
assert_eq!(n.children().len(), 2);

keyhints

keyhints(keys: &Keymap<M>) -> Node<M>: a hint line built from Keymap::bind labels, always ending with tab focus. ambient bindings are not listed.

use cascivo_tui::prelude::*;

let km = Keymap::new().bind("q", "quit", 1).ambient("ctrl+c", 2);
let n: Node<i32> = keyhints(&km);
assert_eq!(render_to_string(&n, 40, 1).unwrap(), "q quit · tab focus");

modal(title: &str, body: Node<M>, on_close: M) -> Node<M>. Centered over the rest of the view. While it is in the tree, focus and keys are trapped inside it, the app keymap is skipped, and Esc emits on_close. The app owns visibility: include the node only while a flag is set. Make it the last child of the root so it paints on top.

use cascivo_tui::prelude::*;

let body: Node<&str> = col("", [text("Delete?").into(), button("Yes", "yes").id("yes")]);
let ui: Node<&str> = col("", [text("page").into(), modal("Confirm", body, "close")]);
let s = render_to_string(&ui, 20, 8).unwrap();
assert!(s.contains("Confirm") && s.contains("Delete?"));
assert!(ui.active_modal().unwrap().find("yes").is_some());

toast, toasts

toast(kind: Kind, msg: &str) -> Node<M> is one bordered message; toasts(items: &[(Kind, String)]) is a bottom-right stack of the newest 3 (MAX_TOASTS). Kind is Info, Success, Warning or Danger; each has a glyph (i, ✓, !, ✗) so it is not colour-only. The app owns lifetimes: push to state on an event and schedule removal with Cmd::tick(2000, Msg::Expire). Place toasts(..) last among the root's children.

use cascivo_tui::prelude::*;

let items = [(Kind::Info, "one".to_string()), (Kind::Danger, "two".to_string())];
let ui: Node = col("", [text("page").into(), toasts(&items)]);
let s = render_to_string(&ui, 20, 8).unwrap();
assert!(s.contains("i one") && s.contains("✗ two"));

Focus, keys, modal and toast behaviour

Themes

Twelve themes: arcade, brutalist, corporate, cyberpunk, dark, flat, light, midnight, minimal, pastel, terminal, warm. Theme::names() lists them and Theme::by_name(name) looks one up. The default is terminal. Choose one at start-up with RunOptions { theme: Some("midnight".into()), ..Default::default() } passed to run_with, with the CASCIVO_THEME environment variable, or at runtime by returning Cmd::SetTheme(name) from update. An unknown name in Cmd::SetTheme paints the error panel, so typos are loud. The colour depth follows the terminal (NO_COLOR and COLORTERM), and focus keeps a bold or reverse cue at every depth.

use cascivo_tui::prelude::*;

assert!(Theme::names().contains(&"midnight"));
assert!(Theme::by_name("midnight").is_some());
let next: Cmd<()> = Cmd::SetTheme("midnight".to_owned());
assert!(matches!(next, Cmd::SetTheme(_)));

Testing

TestApp runs your App headless on a fixed grid with a virtual clock. press("ctrl+k") sends a chord, type_text("abc") types characters, advance(ms) moves time for Cmd::tick, resize(cols, rows) resizes, render() returns the screen as text, cell(x, y) returns a CellView (symbol, colours, theme roles, modifiers), app() reads state, focused() reads the focus id, is_quit() checks for exit, and .theme("dark") selects a theme. For a single node use render_to_string(&node, cols, rows).

use cascivo_tui::prelude::*;

#[derive(Clone)]
enum Msg {
    Inc,
    Quit,
}
struct Counter(i32);
impl App for Counter {
    type Msg = Msg;
    fn update(&mut self, m: Msg) -> Cmd<Msg> {
        match m {
            Msg::Inc => {
                self.0 += 1;
                Cmd::none()
            }
            Msg::Quit => Cmd::Quit,
        }
    }
    fn view(&self) -> Node<Msg> {
        col("", [text(format!("count: {}", self.0)).into()])
    }
    fn keys(&self) -> Keymap<Msg> {
        Keymap::new().bind("+", "add", Msg::Inc).bind("q", "quit", Msg::Quit)
    }
}

let mut t = TestApp::new(Counter(0), 20, 3);
t.press("+").press("+");
assert_eq!(t.render().unwrap(), "count: 2");
assert!(!t.is_quit());
t.press("q");
assert!(t.is_quit());

assert_snapshot(name) compares the screen with tests/snapshots/<name>.txt (in the crate running the test). The file is written when it is missing or when UPDATE_SNAPSHOTS=1 is set; otherwise a mismatch panics with a -expected / +actual line diff. Commit the files and review them like code.

let mut t = TestApp::new(Counter(0), 20, 3);
t.press("+").assert_snapshot("counter_one");
// UPDATE_SNAPSHOTS=1 cargo test   # rewrite after an intended change

TestApp::press panics on a chord that does not parse and TestApp::theme on an unknown theme (the message lists the valid names); both are test-only APIs. The dashboard's own test is tests/example_smoke.rs.

Common errors

MessageCause and fix
unknown class "bg-primary": did you mean "bg-accent"?Not a cascivo class. Use the suggestion; aliases such as primary, destructive, error, foreground, background map to roles.
out of range "gap-99": did you mean "gap-64"?A number above the limit (0..=64, grow-N 0..=16).
variant not allowed "focus:p-1"focus:, selected: and disabled: take only colour and modifier tokens. Use narrow: for layout.
invalid key "ctrl+"A Keymap chord that does not parse. Use ctrl+, alt+, shift+ plus one key or a name (tab, esc, enter, f5).
red error panel at runtimeA class error, bad chord or message loop in the view. The panel names it. Fix and rerun; q or ctrl+c quits.
a widget never gets focusIt has no .id(..).
a modal paints under the pageIt is not the last child of the root.
render_to_string returns Err(TuiError::Class(..))A class string in the tree is invalid; the error carries the token and suggestion.

As Markdown: /docs/using-cascivo-tui.md

← All guides