✨ Features

📦 Installation

Add boxen to your Cargo.toml:

[dependencies]
boxen = "0.3"

For maximum performance, enable caching features:

[dependencies]
boxen = { version = "0.3", features = ["width-cache", "terminal-cache"] }

🚀 Quick Start

use ::boxen::{boxen, builder, BorderStyle, TextAlignment};

fn main() {
    // Simple box with default settings
    let simple = boxen("Hello, World!", None).unwrap();
    println!("{}", simple);
    // ┌─────────────┐
    // │Hello, World!│
    // └─────────────┘

    // Styled box with builder pattern
    let fancy = builder()
        .border_style(BorderStyle::Double)
        .padding(2)
        .text_alignment(TextAlignment::Center)
        .title("Greeting")
        .border_color("blue")
        .render("Hello, World!")
        .unwrap();
    println!("{}", fancy);
}

📚 Examples

Basic Usage

use ::boxen::boxen;

let result = boxen("Simple box", None)
    .unwrap();
println!("{}", result);

┌──────────┐
│Simple box│
└──────────┘

Styled Box

use ::boxen::{builder, BorderStyle};

let result = builder()
    .border_style(BorderStyle::Round)
    .padding(1)
    .title("Status")
    .border_color("green")
    .render("All systems operational")
    .unwrap();

╭─── Status ────╮
│               │
│ All systems   │
│ operational   │
│               │
╰───────────────╯

Convenience Functions

use ::boxen::{simple_box, double_box, round_box};

println!("{}", simple_box("Default style"));
println!("{}", double_box("Double border"));
println!("{}", round_box("Round corners"));

Advanced Styling

use ::boxen::{builder, BorderStyle, TextAlignment, TitleAlignment, Float};

let result = builder()
    .border_style(BorderStyle::Bold)
    .padding((2, 4, 2, 4))  // top, right, bottom, left
    .margin(1)
    .text_alignment(TextAlignment::Center)
    .title_alignment(TitleAlignment::Center)
    .float(Float::Center)
    .width(40)
    .title("🎉 Celebration")
    .border_color("#ff6b6b")
    .background_color("#ffe66d")
    .render("Congratulations!\nYou've mastered boxen!")
    .unwrap();

🎨 Border Styles

Boxen supports various border styles:

┌─┐
│ │
└─┘

╔═╗
║ ║
╚═╝

╭─╮
│ │
╰─╯

┏━┓
┃ ┃
┗━┛

╓─╖
║ ║
╙─╜

╒═╕
│ │
╘═╛

+--+
|  |
+--+

🌈 Color Support

Boxen supports multiple color formats:

use ::boxen::builder;

// Named colors (16 standard terminal colors)
builder()
    .border_color("red")
    .background_color("blue");

// Hex colors
builder()
    .border_color("#ff0000")
    .background_color("#0000ff");

// RGB colors
builder()
    .border_color((255, 0, 0))
    .background_color((0, 0, 255));

// Dim borders for subtle styling
builder()
    .border_color("cyan")
    .dim_border(true);

Available named colors: black, red, green, yellow, blue, magenta, cyan, white, bright-black, bright-red, bright-green, bright-yellow, bright-blue, bright-magenta, bright-cyan, bright-white

⚡ Performance

Boxen is highly optimized for speed and memory efficiency:

Benchmark Results

Core Optimizations

✅ Thread-local string pooling - Reduces allocations by 24-87%
✅ Smart buffer management - Pre-allocated buffers with capacity hints
✅ Efficient ANSI handling - Proper escape sequence processing
✅ Unicode optimization - Fast width calculations

Optional Performance Features

Enable caching for even better performance:

[dependencies]
boxen = { version = "0.3", features = ["width-cache", "terminal-cache"] }

Performance gains:

• 90% cache hit rates for typical workloads

• Lock-free thread-local caching
• Automatic cache invalidation on terminal resize (Unix)
• Configurable cache sizes and TTL

📖 See Performance Guide for detailed information.

🎯 Use Cases

// Success messages
println!("{}",
    simple_box("✓ Build successful!")
);

// Error messages
println!("{}",
    builder()
        .border_color("red")
        .render("✗ Build failed")
        .unwrap()
);

// System status
println!("{}",
    builder()
        .title("System Status")
        .border_color("green")
        .render("All systems operational")
        .unwrap()
);

// User notifications
println!("{}",
    builder()
        .title("🔔 Notification")
        .padding(2)
        .render("You have 3 new messages")
        .unwrap()
);

📖 Documentation

Guides

• 📘 API Documentation - Complete API reference
• 📗 Usage Guide - Detailed usage examples
• 📙 Customization Guide - Advanced styling techniques
• 📕 Performance Guide - Optimization strategies
• 📔 Migration Guide - Upgrading from v0.1.x

Examples

Run the included examples to see boxen in action:

# Basic usage patterns
cargo run --example main_api_demo

# Color demonstrations
cargo run --example color_demo

# Comprehensive feature showcase
cargo run --example comprehensive_demo

# Performance testing
cargo run --example performance_demo

# Caching features demo
cargo run --example caching_demo --features width-cache,terminal-cache

# Memory profiling
cargo run --example memory_profiling --features dhat-heap

# Error handling patterns
cargo run --example error_handling_demo

# Fullscreen mode
cargo run --example fullscreen_demo

# Interactive clock with spinner
cargo run --example clock_spinner

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🐛 Report bugs - Open an issue with details
2. 💡 Suggest features - Share your ideas
3. 📝 Improve docs - Help others learn
4. 🔧 Submit PRs - Fix bugs or add features

Please read our Contributing Guide for details.

📜 License

This project is licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

🙏 Acknowledgments

• Inspired by the original boxen TypeScript library by Sindre Sorhus
• Built with ❤️ for the Rust community
• Thanks to all contributors