# y4seenx 🎨

**The Ultimate Gradient Color Package for Python**

Create stunning terminal gradients with ANY color format! Better, faster, and more feature-rich than alternatives.

[![PyPI version](https://badge.fury.io/py/y4seenx.svg)](https://badge.fury.io/py/y4seenx)
[![Python Support](https://img.shields.io/pypi/pyversions/y4seenx.svg)](https://pypi.org/project/y4seenx/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🎨 **Any Color Format**: HEX, RGB, HSL, HSV, CMYK - we support them all!
- 🌈 **Multiple Gradient Types**: Horizontal, Vertical, Diagonal, Radial
- ⚡ **Zero Dependencies**: Pure Python, no external libraries needed
- 🎭 **Animations**: Wave, Pulse, Rainbow effects
- 📦 **Beautiful Presets**: 20+ pre-made stunning gradients
- 💻 **Cross-Platform**: Works on Windows, macOS, Linux
- 🔥 **Blazing Fast**: Optimized for performance
- 🎯 **Easy API**: Simple and intuitive, inspired by pystyle but better!

## 📦 Installation

```bash
pip install y4seenx
```

## 🚀 Quick Start

```python
from y4seenx import Gradient, Presets, Colorate, Colors, Write

# Simple gradient
text = Gradient('#FF0000', '#0000FF').horizontal('Hello World!')
print(text)

# Use beautiful presets
banner = """
╔═══════════════════════════════╗
║     WELCOME TO y4seenx!      ║
╚═══════════════════════════════╝
"""
print(Colorate.Horizontal(Colors.fire, banner))

# Animated input (just like pystyle!)
choice = Write.input('[Menu] >> ', Colors.blue_to_cyan, interval=0.01)

# Multiple color gradient
rainbow = Gradient('#FF0000', '#FF7F00', '#FFFF00', '#00FF00', '#0000FF', '#4B0082', '#9400D3')
print(rainbow.horizontal('RAINBOW TEXT!'))
```

## 📖 Documentation

### Creating Gradients

#### From HEX Colors
```python
from y4seenx import Gradient

# Two colors
gradient = Gradient('#FF0000', '#0000FF')

# Multiple colors
gradient = Gradient('#FF0000', '#00FF00', '#0000FF')

# Short HEX
gradient = Gradient('#F00', '#00F')

# With 0x prefix
gradient = Gradient('0xFF0000', '0x0000FF')
```

#### From RGB Colors
```python
gradient = Gradient((255, 0, 0), (0, 0, 255))
```

#### From Named Colors
```python
gradient = Gradient('red', 'blue', 'green')
# Supports: red, green, blue, yellow, cyan, magenta, white, black, 
# orange, purple, pink, lime, navy, teal, gold, silver, gray, maroon
```

#### From HSL/HSV
```python
from y4seenx import Color

color1 = Color.from_hsl(0, 100, 50)    # Red in HSL
color2 = Color.from_hsv(240, 100, 100) # Blue in HSV
gradient = Gradient(color1, color2)
```

### Applying Gradients

```python
from y4seenx import Gradient

gradient = Gradient('#FF0000', '#0000FF')

# Horizontal gradient (left to right)
text = gradient.horizontal('Hello World!')

# Vertical gradient (top to bottom)
text = gradient.vertical('Line 1\nLine 2\nLine 3')

# Diagonal gradient
text = gradient.diagonal('Diagonal Text!')

# Radial gradient (from center)
text = gradient.radial('Radial Text!')
```

### Using Presets

```python
from y4seenx import Presets, Colorate

# Pre-made beautiful gradients
print(Colorate.Horizontal(Presets.FIRE, 'Fire gradient!'))
print(Colorate.Horizontal(Presets.OCEAN, 'Ocean gradient!'))
print(Colorate.Horizontal(Presets.SUNSET, 'Sunset gradient!'))
print(Colorate.Horizontal(Presets.RAINBOW, 'Rainbow gradient!'))
print(Colorate.Horizontal(Presets.CYBERPUNK, 'Cyberpunk gradient!'))
print(Colorate.Horizontal(Presets.MATRIX, 'Matrix gradient!'))
```

#### Available Presets
- `FIRE` - Red → Orange → Yellow flame effect
- `OCEAN` - Deep blue → Light blue ocean waves
- `FOREST` - Dark green → Light green forest
- `SUNSET` - Red → Orange → Yellow → Light yellow
- `RAINBOW` - Full rainbow spectrum
- `NEON_PINK`, `NEON_BLUE`, `NEON_GREEN` - Vibrant neon colors
- `PASTEL_RAINBOW`, `PASTEL_PINK` - Soft pastel colors
- `DARK_PURPLE`, `DARK_BLUE` - Dark mode friendly
- `CYBERPUNK` - Magenta → Cyan cyberpunk style
- `MATRIX` - Green matrix effect
- `GRAY_SCALE`, `BLACK_WHITE` - Monochrome

### Animations

```python
from y4seenx import Animate, Write, Gradient, Presets

# Typing animation
Write.print('Loading...', Presets.FIRE, interval=0.05)

# Animated input
name = Write.input('Enter name: ', Presets.BLUE_CYAN, interval=0.02)

# Wave animation
Animate.wave('WAVE EFFECT!', Presets.RAINBOW, cycles=3, speed=0.05)

# Pulse animation
Animate.pulse('PULSE!', '#FF0000', pulses=5, speed=0.1)

# Rainbow cycle
Animate.rainbow_cycle('RAINBOW!', cycles=3, speed=0.05)
```

### Text Effects

```python
from y4seenx import Box, Presets

# Simple box
boxed = Box.simple('Hello World!', Presets.FIRE, padding=2)
print(boxed)

# Double-line box
boxed = Box.double('Important Message!', Presets.OCEAN, padding=3)
print(boxed)
```

### Color Manipulation

```python
from y4seenx import Color

# Create color
color = Color.from_hex('#FF5733')

# Convert formats
print(color.to_hex())    # #ff5733
print(color.to_rgb())    # (255, 87, 51)
print(color.to_hsl())    # (9.0, 100.0, 60.0)
print(color.to_hsv())    # (9.0, 80.0, 100.0)

# Lighten/Darken
lighter = color.lighten(0.2)   # 20% lighter
darker = color.darken(0.2)     # 20% darker

# Interpolate between colors
color1 = Color.from_hex('#FF0000')
color2 = Color.from_hex('#0000FF')
middle = color1.interpolate(color2, 0.5)  # Purple
```

## 🎯 Comparison with pystyle

If you're familiar with `pystyle`, here's how to migrate:

```python
# pystyle
from pystyle import Colorate, Colors, Write
print(Colorate.Horizontal(Colors.blue_to_cyan, 'Text'))
choice = Write.Input('>> ', Colors.blue_to_cyan, interval=0.01)

# y4seenx (same API!)
from y4seenx import Colorate, Colors, Write
print(Colorate.Horizontal(Colors.blue_to_cyan, 'Text'))
choice = Write.input('>> ', Colors.blue_to_cyan, interval=0.01)
```

**Why choose y4seenx over pystyle?**
- ✅ More gradient types (diagonal, radial)
- ✅ More color formats (HEX, RGB, HSL, HSV, CMYK)
- ✅ More presets (20+ vs 10)
- ✅ Zero dependencies
- ✅ Better performance
- ✅ More animations
- ✅ Active development

## 🎨 Real-World Example

```python
from y4seenx import Gradient, Colorate, Colors, Write, Box, Presets
import asyncio

def clear():
    import os
    os.system('cls' if os.name == 'nt' else 'clear')

def show_banner():
    banner = """
╔══════════════════════════════════════════════════════╗
║                 MY AWESOME APP                      ║
║              The Best Tool Ever!                    ║
╚══════════════════════════════════════════════════════╝
    """
    print(Colorate.Horizontal(Colors.cyberpunk, banner))

async def main_menu():
    while True:
        clear()
        show_banner()
        
        menu = """
        [01] Start Process
        [02] View Results  
        [03] Settings
        [04] Exit
        """
        print(Colorate.Horizontal(Colors.blue_to_cyan, menu))
        
        choice = Write.input('[Menu] >> ', Colors.neon_blue, interval=0.01)
        
        if choice == '1':
            Write.print('Starting process...', Colors.neon_green, interval=0.02)
        elif choice == '4':
            Write.print('Goodbye!', Colors.fire, interval=0.03)
            break

if __name__ == '__main__':
    asyncio.run(main_menu())
```

## 📝 Advanced Usage

### Custom Gradient with Multiple Stops

```python
# Create a complex gradient with many color stops
gradient = Gradient(
    '#FF0000',  # Red
    '#FF7F00',  # Orange
    '#FFFF00',  # Yellow
    '#00FF00',  # Green
    '#0000FF',  # Blue
    '#4B0082',  # Indigo
    '#9400D3'   # Violet
)

print(gradient.horizontal('Full Rainbow Spectrum!'))
```

### Radial Gradient with Custom Center

```python
# Center the gradient at a specific point
text = """
    *
   ***
  *****
 *******
*********
"""

gradient = Gradient('#FFD700', '#FF0000')
print(gradient.radial(text, center=(0.5, 0.0)))  # Center at top
```

## 🤝 Contributing

Contributions are welcome! Feel free to:
- Report bugs
- Suggest features
- Submit pull requests

## 📄 License

MIT License - feel free to use in your projects!

## 🌟 Star History

If you like this project, please give it a star ⭐

## 👨‍💻 Author

Made with ❤️ by **y4seenx**

---

**y4seenx** - Making terminals beautiful, one gradient at a time! 🎨
