Tca-Ratatui

Ratatui integration for TCA themes. Loads and resolves TCA theme files into ratatui::style::Color values ready to use in widgets and styles.

Installation

cargo add tca-ratatui

Loading a single theme

By name, slug, or file path

use tca_ratatui::TcaTheme;

// Theme name or slug — checks user themes, then built-ins
let theme = TcaTheme::new(Some("Tokyo Night"));
let theme = TcaTheme::new(Some("tokyo-night"));
let theme = TcaTheme::new(Some("nordDark"));   // flexible slug matching

// Exact file path
let theme = TcaTheme::new(Some("path/to/mytheme.toml"));

// Auto-detect from terminal dark/light mode, then fall back to built-in default
let theme = TcaTheme::new(None);
let theme = TcaTheme::default(); // same as new(None)

From a TOML string

use tca_ratatui::TcaTheme;

let theme = TcaTheme::try_from(toml_str).expect("invalid theme");

From a tca_types::Theme

use tca_ratatui::TcaTheme;
use tca_types::BuiltinTheme;

let raw = BuiltinTheme::Nord.theme();
let theme = TcaTheme::try_from(raw)?;

Programmatically with TcaThemeBuilder

use tca_ratatui::{TcaThemeBuilder, Semantic, Ui};
use ratatui::style::Color;

let theme = TcaThemeBuilder::new()
    .semantic(Semantic {
        error:   Color::Rgb(255, 80, 80),
        warning: Color::Rgb(255, 200, 0),
        ..Default::default()
    })
    .ui(Ui {
        bg_primary: Color::Rgb(28, 28, 28),
        fg_primary: Color::Rgb(238, 238, 236),
        ..Default::default()
    })
    .build();

Loading a collection of themes

use tca_ratatui::TcaThemeCursor;

// All built-in themes
let mut cursor = TcaThemeCursor::with_builtins();

// User-installed themes from XDG data dir
let mut cursor = TcaThemeCursor::with_user_themes();

// Built-ins merged with user themes (user overrides on name match)
let mut cursor = TcaThemeCursor::with_all_themes();

// From an explicit list
let mut cursor = TcaThemeCursor::new(vec![theme_a, theme_b]);

If you need the raw tca_types::Theme type instead, the generic ThemeCursor<T> is also re-exported:

use tca_ratatui::ThemeCursor;
use tca_types::Theme;

let mut cursor: ThemeCursor<Theme> = ThemeCursor::with_builtins();

Theme cursor navigation

use tca_ratatui::{TcaTheme, TcaThemeCursor};

let mut cursor = TcaThemeCursor::with_builtins();

// Current theme without moving
let theme: &TcaTheme = cursor.peek().unwrap();

// Advance (wraps at end)
let theme: &TcaTheme = cursor.next().unwrap();

// Retreat (wraps at start)
let theme: &TcaTheme = cursor.prev().unwrap();

// Inspect without moving
println!("Showing: {}", cursor.peek().unwrap().meta.name);
println!("{} themes available", cursor.len());

// Iterate all themes without cycling
for theme in cursor.themes() {
    println!("{}", theme.meta.name);
}

Using theme colors

use ratatui::style::Style;

let normal    = Style::default().fg(theme.ui.fg_primary).bg(theme.ui.bg_primary);
let secondary = Style::default().fg(theme.ui.fg_secondary);
let muted     = Style::default().fg(theme.ui.fg_muted);
let border    = Style::default().fg(theme.ui.border_primary);
let selection = Style::default().bg(theme.ui.selection_bg).fg(theme.ui.selection_fg);
let error     = Style::default().fg(theme.semantic.error);
let warning   = Style::default().fg(theme.semantic.warning);
let ansi_red  = Style::default().fg(theme.ansi.red);

// Palette ramps (if the theme defines them)
if let Some(ramp) = theme.palette.get_ramp("neutral") {
    let dark  = ramp.get(0); // darkest
    let light = ramp.get(ramp.len() - 1); // lightest
}

TcaTheme fallback behavior

TcaTheme::new() resolution order:

1. User theme files — ~/.local/share/tca/themes/<name>.toml, or an exact file path
2. Built-in themes — always available, no installation required
3. Auto-detect — dark or light built-in based on the terminal's background color

If semantic or ui color references can't be resolved, they fall back to sensible ratatui named colors (e.g. Color::Red for semantic.error).

Built-in themes

Color sections

TcaTheme
├── meta      — name, slug, author, version, description, dark
├── ansi      — 16 ANSI colors (black, red, … bright_white) as Color::Rgb
├── semantic  — error, warning, info, success, highlight, link
├── ui        — bg_primary/secondary, fg_primary/secondary/muted,
│               border_primary/muted, cursor_primary/muted,
│               selection_bg/fg
├── palette   — named color ramps (e.g. neutral.0–7, red.0–2)
└── base16    — base00–base0F if the theme defines them

Features

# Builder-only, no file I/O or widgets
tca-ratatui = { version = "0.4", default-features = false }

# With widgets only
tca-ratatui = { version = "0.4", features = ["widgets"] }

Examples

# Interactive theme browser (cycles through all themes)
cargo run --example picker --features widgets

# Browse themes from a directory
cargo run --example picker --features widgets -- path/to/themes/

# Browse built-ins only
cargo run --example picker --features widgets -- --builtin

License

MIT