# Aurora 🎨

> _"Because life is too short for black and white terminals"_ 🌈

**A powerful terminal formatting and rendering library for Elixir**

Aurora is a comprehensive, dependency-free library for terminal formatting, ANSI colors, and text rendering. Transform your terminal output into a colorful, professional experience with minimal effort.

## 🌟 Overview

Aurora provides a complete solution for terminal text formatting with:

- **Rich Color System**: Support for HEX, RGB, HSV, HSL, CMYK, ARGB formats with automatic conversion
- **ANSI Effects**: Bold, italic, underline, blink, reverse, and more
- **Advanced Formatting**: Text alignment, indentation, tables, and structured layouts
- **Interactive Components**: Questions, menus, progress bars, breadcrumbs
- **Gradient Support**: Apply beautiful gradients to text with orientation control
- **JSON Formatting**: Syntax-highlighted JSON output
- **CLI Tool**: Full-featured command-line interface
- **Modular Architecture**: Clean, extensible design for easy integration

### 🚀 Potential

While Aurora already provides extensive functionality, the library has significant untapped potential:

- **~98 public functions** available at the code level
- **~21 CLI commands** currently exposed
- **~77% of functionality** not yet accessible via CLI
- **Extensible architecture** ready for new features

The modular design makes it easy to add new capabilities, whether through the library API or CLI commands.

## 📦 Installation

### As a Dependency

Add Aurora to your `mix.exs`:

```elixir
def deps do
  [
    {:aurora, "~> 2.0"}
  ]
end
```

Then run:

```bash
mix deps.get
```

### As a CLI Tool

Build the executable:

```bash
mix escript.build
```

This generates the `./aurora` executable.

## 🎯 Quick Start

### Library Usage

```elixir
# Basic messages
Aurora.Printer.success("Operation completed")
Aurora.Printer.error("An error occurred")
Aurora.Printer.warning("Important warning")
Aurora.Printer.info("Useful information")

# Formatted text
Aurora.Format.format("Hello World!", color: :primary) |> IO.puts()

# Tables
Aurora.Printer.table(
  ["Name", "Age", "Role"],
  [["John", "25", "Developer"], ["Jane", "30", "Designer"]]
)

# Interactive components
name = Aurora.Printer.question("What is your name?")
if Aurora.Printer.yesno("Continue?") == :yes do
  # ...
end
```

### CLI Usage

```bash
# Formatted text
./aurora --text="Hello World!" --color=primary --bold

# Messages
./aurora --success="Operation completed"
./aurora --error="An error occurred"

# Tables
./aurora --table --headers="Name,Age" --row="John,25" --row="Jane,30"

# Color conversion
./aurora --convert --from="#FF0000" --to=rgb
```

## 📚 Core Features

### Color Management

Aurora provides comprehensive color management with multiple formats, manipulation, blending, palette generation, color scheme calculation, and WCAG contrast detection.

#### Color Formats

Aurora supports multiple color formats with automatic conversion:

- **HEX**: `"#FF0000"`, `"#A1E7FA"`
- **RGB**: `{255, 0, 0}`
- **ARGB**: `{255, 255, 0, 0}`
- **HSV**: `{0.0, 1.0, 1.0}`
- **HSL**: `{0.0, 1.0, 0.5}`
- **CMYK**: `{0.0, 1.0, 1.0, 0.0}`
- **Named Colors**: `:primary`, `:error`, `:success`, etc.

**Example:**

```elixir
# Automatic format conversion
color = Aurora.Color.to_color_info("#FF0000")
color = Aurora.Color.to_color_info({255, 0, 0})
color = Aurora.Color.to_color_info(:primary)

# Color manipulation
lighter = Aurora.Color.lighten(color, 2)  # 2 tones lighter
darker = Aurora.Color.darken(color, 3)   # 3 tones darker

# Blend colors
mixed = Aurora.Color.blend("#FF0000", "#0000FF", 0.5)  # Mix red and blue

# Generate palettes
{shades, base, tints} = Aurora.Color.generate_palette(color, 5, 5)
shades_only = Aurora.Color.generate_shades(color, 5)
tints_only = Aurora.Color.generate_tints(color, 5)

# Calculate color schemes
analogous = Aurora.Color.analogous(color, 2, 30.0)  # Adjacent colors
mono = Aurora.Color.monochromatic(color, 5)  # Same hue, different saturation/lightness
triad = Aurora.Color.triadic(color)  # 3 equidistant colors
complement = Aurora.Color.complementary(color)  # Opposite color
split_comp = Aurora.Color.split_complementary(color, 30.0)  # Split-complementary
square_colors = Aurora.Color.square(color)  # 4 equidistant colors
compound_colors = Aurora.Color.compound(color, 60.0)  # Tetradic scheme
tones = Aurora.Color.tones(color, 9)  # Tonal variations

# WCAG contrast detection
ratio = Aurora.Color.contrast_ratio(white, black)  # 21.0 (maximum)
meets_aaa = Aurora.Color.meets_contrast_ratio?(white, black, :AAA, :normal)  # true
level = Aurora.Color.contrast_level(white, black)  # :AAA_large

# Apply colors
colored = Aurora.Color.apply_color("Hello!", :primary)
background = Aurora.Color.apply_background_color("Text", :error)
```

### Text Formatting

Comprehensive text formatting with alignment, indentation, and effects:

```elixir
# Basic formatting
chunk = %Aurora.Structs.ChunkText{text: "Hello world", color: :primary}
format_info = %Aurora.Structs.FormatInfo{chunks: [chunk], align: :center}
result = Aurora.Format.format(format_info)

# Multiple chunks with different colors
chunks = [
  %Aurora.Structs.ChunkText{text: "Error: ", color: :error},
  %Aurora.Structs.ChunkText{text: "File not found", color: :warning}
]
result = Aurora.Format.format(chunks)
```

### ANSI Effects

Apply various text effects:

- `:bold`, `:dim`, `:italic`, `:underline`
- `:blink`, `:reverse`, `:hidden`, `:strikethrough`, `:link`

```elixir
# Single effect
Aurora.Effects.apply_effect("Hello", :bold)

# Multiple effects
Aurora.Effects.apply_multiple_effects("Hello", [:bold, :underline])

# From EffectInfo struct
effects = %Aurora.Structs.EffectInfo{bold: true, italic: true}
Aurora.Effects.apply_effect_info("Hello", effects)
```

### Gradients

Apply beautiful gradients to text:

```elixir
# Horizontal gradient
Aurora.Color.apply_gradient("Hello", [:red, :blue])

# Vertical gradient
Aurora.Color.apply_gradient("Hello", [:red, :blue], orientation: :vertical)

# Reverse gradient
Aurora.Color.apply_gradient("Hello", [:red, :blue], orientation: :reverse)

# Logo formatting with gradients
lines = ["  ████  ", " ██████ ", "████████"]
{formatted, _hexes} = Aurora.Format.format_logo(lines, gradient_orientation: :horizontal)
```

### Tables

Create formatted tables with advanced options:

```elixir
headers = ["Name", "Age", "Role"]
rows = [
  [%Aurora.Structs.ChunkText{text: "John", color: :primary},
   %Aurora.Structs.ChunkText{text: "25", color: :secondary}],
  [%Aurora.Structs.ChunkText{text: "Jane", color: :primary},
   %Aurora.Structs.ChunkText{text: "30", color: :secondary}]
]

Aurora.Printer.table(headers, rows,
  table_align: :center,
  header_align: [:left, :center, :right]
)
```

### Interactive Components

Build interactive CLI interfaces:

```elixir
# Simple question
name = Aurora.Printer.question("What is your name?")

# Question with options
editor = Aurora.Printer.question_with_options(
  "Which editor do you prefer?",
  [{"vscode", "VS Code"}, {"nvim", "Neovim"}]
)

# Yes/No confirmation
if Aurora.Printer.yesno("Continue?") == :yes do
  # ...
end

# Menu
Aurora.Printer.menu("Options", ["Option 1", "Option 2", "Option 3"])
```

### JSON Formatting

Syntax-highlighted JSON output:

```elixir
data = %{name: "John", age: 30, active: true}
formatted = Aurora.Format.JSON.format_json(data)
IO.puts(formatted)
```

## 🖥️ CLI Reference

### Basic Commands

```bash
# Text formatting
./aurora --text="Hello" --color=primary --bold

# Messages
./aurora --success="Operation completed"
./aurora --error="An error occurred"
./aurora --warning="Be careful"
./aurora --info="Processing..."

# Components
./aurora --header="Welcome" --align=center
./aurora --separator --char="=" --color=primary
./aurora --breadcrumbs --items="Home,Projects,Aurora"
./aurora --bar --current=50 --total=100

# Tables
./aurora --table --headers="Name,Age" --row="John,25" --row="Jane,30"

# Color conversion
./aurora --convert --from="#FF0000" --to=rgb
```

### Getting Help

```bash
# General help
./aurora --help

# Command-specific help
./aurora --text --help
./aurora --message --help
./aurora --table --help
./aurora --convert --help

# Examples
./aurora --examples
```

### Raw Mode

Capture ANSI codes for use in scripts:

```bash
result=$(./aurora --text="Success" --color=success --bold --raw)
echo "$result"
```

## 🎨 Available Colors

### Basic Colors

- `:primary`, `:secondary`, `:ternary`, `:quaternary`

### Status Colors

- `:success`, `:warning`, `:error`, `:info`, `:debug`

### Special Colors

- `:critical`, `:alert`, `:emergency`, `:happy`, `:notice`, `:menu`, `:no_color`

## ✨ Available Effects

- `:bold`, `:italic`, `:underline`, `:dim`
- `:blink`, `:reverse`, `:hidden`, `:strikethrough`, `:link`

## 📖 API Documentation

### Main Modules

- **`Aurora.Color`**: Color management and conversion
- **`Aurora.Format`**: Text formatting and layout
- **`Aurora.Effects`**: ANSI effects application
- **`Aurora.Convert`**: Data conversion utilities
- **`Aurora.Printer`**: High-level printing API
- **`Aurora.Format.JSON`**: JSON formatting with syntax highlighting

### Key Functions

#### Color Module

- `to_color_info/1` - Convert any format to ColorInfo
- `apply_color/3` - Apply color to text
- `apply_gradient/3` - Apply gradients to text
- `lighten/2`, `darken/2` - Brightness manipulation
- `hex_to_rgb/1`, `rgb_to_hex/1` - Format conversion
- `rgb_to_hsv/1`, `hsv_to_rgb/1` - HSV conversion
- `rgb_to_hsl/1`, `hsl_to_rgb/1` - HSL conversion
- `rgb_to_cmyk/1`, `cmyk_to_rgb/1` - CMYK conversion

#### Format Module

- `format/1` - Format FormatInfo or chunks
- `format_logo/2` - Format ASCII art with gradients
- `clean_ansi/1` - Remove ANSI codes
- `visible_length/1` - Calculate visible text length
- `format_message_with_prefix/4` - Format messages with icons

#### Effects Module

- `apply_effect/2` - Apply single effect
- `apply_multiple_effects/2` - Apply multiple effects
- `apply_effects/2` - Apply effects from keyword list
- `available_effects/0` - List all available effects
- `valid_effect?/1` - Validate effect name

#### Printer Module

- `message/1` - Print formatted message
- `success/2`, `error/2`, `warning/2`, `info/2` - Status messages
- `table/3` - Print formatted table
- `header/2`, `separator/1`, `breadcrumbs/2`, `bar/2` - Components
- `question/2`, `yesno/2`, `menu/3` - Interactive components

## 🔧 Development

### Running Tests

```bash
mix test
```

### Code Quality

```bash
mix quality
```

### Building Documentation

```bash
mix docs
```

### Building Executable

```bash
mix escript.build
```

## 📊 Architecture

Aurora follows a modular architecture:

- **Core Modules**: `Color`, `Format`, `Effects`, `Convert` - Core functionality
- **Printer Modules**: `Basic`, `Components`, `Interactive`, `Tables` - High-level APIs
- **CLI Modules**: `Parser`, `Handler`, `Formatter`, `Validator`, `Help` - CLI infrastructure
- **Executors**: Specialized command executors for each command type
- **Structs**: `ChunkText`, `ColorInfo`, `EffectInfo`, `FormatInfo` - Data structures

This architecture makes it easy to:

- Add new features
- Extend existing functionality
- Integrate with other systems
- Maintain and test

### Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## 📄 License

Apache 2.0 - See [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

Aurora is part of the Ypsilon project ecosystem, designed to provide powerful, elegant tools for Elixir developers.

---

**Made with ❤️ for colorful terminals everywhere**