Hojicha

The Elm Architecture for Terminal UIs in Rust

Hojicha implements The Elm Architecture for terminal applications. Built on Ratatui, inspired by Bubbletea.

Features

• Simple Architecture - Model-View-Update pattern
• High Performance - Priority event processing with adaptive queues
• Async Native - First-class async/await, cancellation, streams
• Component Library - Pre-built UI components
• Testing Utilities - Headless mode, deterministic testing
• Metrics - Built-in performance monitoring

Installation

[dependencies]
hojicha = "0.2"  # Includes core + runtime
# Or if you want components:
# hojicha = { version = "0.2", features = ["pearls"] }

Or use individual crates if you need fine-grained control:

[dependencies]
hojicha-core = "0.2"
hojicha-runtime = "0.2"
hojicha-pearls = "0.2"  # Optional: UI components

Quick Start

use hojicha::prelude::*;
use ratatui::widgets::{Block, Borders, Paragraph};

struct Counter {
    value: i32,
}

impl Model for Counter {
    type Message = ();

    fn update(&mut self, event: Event<()>) -> Cmd<()> {
        match event {
            Event::Key(key) => match key.key {
                Key::Up => self.value += 1,
                Key::Down => self.value -= 1,
                Key::Char('q') => return quit(),
                _ => {}
            },
            _ => {}
        }
        Cmd::noop()
    }

    fn view(&self, frame: &mut Frame, area: Rect) {
        let text = format!("Counter: {}\n\nUp/Down: change | q: quit", self.value);
        let widget = Paragraph::new(text)
            .block(Block::default().borders(Borders::ALL).title("Counter"));
        frame.render_widget(widget, area);
    }
}

fn main() -> Result<()> {
    Program::new(Counter { value: 0 })?.run()
}

Architecture

The Elm Architecture consists of:

Common Patterns

Async Operations

fn update(&mut self, event: Event<Msg>) -> Cmd<Msg> {
    match event {
        Event::User(Msg::FetchData) => {
            spawn(async {
                let data = fetch_api().await.ok()?;
                Some(Msg::DataLoaded(data))
            })
        }
        _ => Cmd::noop()
    }
}

Timers

fn init(&mut self) -> Cmd<Msg> {
    every(Duration::from_secs(1), |_| Msg::Tick)
}

Stream Subscriptions

let stream = websocket.messages().map(Msg::WsMessage);
let subscription = program.subscribe(stream);

Components

Available via hojicha-pearls:

Input: TextInput, TextArea, Button
Display: List, Table, Tabs, Modal, ProgressBar, Spinner
Layout: Grid, FloatingElement, StatusBar, Viewport

Testing

#[test]
fn test_counter() {
    TestHarness::new(Counter { value: 0 })
        .send_event(Event::Key(KeyEvent::new(Key::Up)))
        .run()
        .assert_model(|m| m.value == 1);
}

Performance Metrics

let program = Program::new(model)?
    .with_priority_config(PriorityConfig {
        enable_metrics: true,
        ..Default::default()
    });

// Export metrics
program.metrics_json();
program.metrics_prometheus();

Advanced Features

Priority Event Processing

1. Critical: Quit, suspend
2. High: User input (keyboard, mouse)
3. Normal: User messages, timers
4. Low: Resize, background tasks

Cancellable Operations

let handle = program.spawn_cancellable(|token| async move {
    while !token.is_cancelled() {
        process_batch().await;
    }
});

Documentation

• Cookbook - Real-World Patterns ⭐ NEW!
• Common Patterns
• Architecture Guide
• Development Guide
• Testing Guide
• API Reference

Examples

# Progressive Tutorial Series (Start Here!)
cargo run --bin tutorial_01_hello -p hojicha-examples    # Hello World basics
cargo run --bin tutorial_02_counter -p hojicha-examples  # State management  
cargo run --bin tutorial_03_forms -p hojicha-examples    # Input handling
cargo run --bin tutorial_04_lists -p hojicha-examples    # Lists and navigation
cargo run --bin tutorial_05_screens -p hojicha-examples  # Multiple screens

# Complete Applications
cargo run --bin todo_list -p hojicha-examples      # Full todo app with persistence
cargo run --bin text_editor -p hojicha-examples    # Simple text editor
cargo run --bin file_manager -p hojicha-examples   # Dual-pane file manager

# Feature Examples
cargo run --bin tutorial -p hojicha-examples       # Interactive tutorial
cargo run --bin showcase -p hojicha-examples       # Component showcase  
cargo run --bin async_examples -p hojicha-examples # Async patterns

See examples/README.md for the complete list and learning path.

Contributing

See CONTRIBUTING.md.

License

GPL-3.0