aurora

# Changelog

Todos los cambios notables a este proyecto se documentarán en este archivo.

El formato está basado en [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
y este proyecto adhiere a [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [2.0.0] - 2025-11-14

### 🎉 Nueva Versión Mayor

Versión 2.0.0 con mejoras significativas en CLI, cobertura de tests y nuevas funcionalidades. Esta versión introduce cambios importantes en el comportamiento por defecto y añade múltiples características nuevas para mejorar la experiencia de uso.

### ✨ Nuevas Características

#### 🔄 Cambios en Comportamiento por Defecto

- **Impresión automática**: Por defecto, Aurora ahora imprime automáticamente el resultado procesado a stdout usando `IO.puts`
- **Flag `--raw`**: Nuevo flag que devuelve el string con códigos ANSI sin procesar (sin escape en macOS, sin newline extra)
  - Útil para capturar output en variables de bash: `result=$(./aurora --text="Hello" --raw)`
  - En modo raw, usa `IO.write` en lugar de `IO.puts` para evitar newlines adicionales
- **Efectos por bloque de texto**: Los flags de efectos (`--bold`, `--italic`, `--dim`, `--underline`, `--blink`, `--reverse`, `--hidden`, `--strikethrough`, `--link`) ahora se aplican solo a su bloque de texto correspondiente (definido por `--text`), no a todos los chunks

#### 🎨 Conversión de Colores Completa

- **Nuevo modo `--convert`**: Permite convertir colores entre diferentes formatos
- **Formatos soportados**: hex, rgb, argb, hsv, hsl, cmyk
- **Entrada flexible**: Acepta colores en múltiples formatos:
  - Hex: `--from="#FF0000"`
  - RGB tuple: `--from="{255,0,0}"`
  - ARGB tuple: `--from="{128,255,0,0}"`
  - Nombres de color: `--from="primary"`
- **Salida formateada**: Convierte a cualquier formato especificado con `--to`
- **Manejo de errores**: Validación y mensajes de error claros para conversiones inválidas

#### 📨 Comandos de Mensaje (Estilo Aegis)

Nuevos comandos predefinidos para mensajes comunes con estilos automáticos:

- `--success="mensaje"` - Mensaje de éxito con prefijo [✓] y color success
- `--error="mensaje"` - Mensaje de error con prefijo [X] y color error
- `--warning="mensaje"` - Mensaje de advertencia con prefijo [!] y color warning
- `--info="mensaje"` - Mensaje informativo con prefijo [i] y color info
- `--debug="mensaje"` - Mensaje de debug con prefijo [d] y color debug
- `--notice="mensaje"` - Mensaje de aviso con prefijo [n] y color info
- `--critical="mensaje"` - Mensaje crítico con prefijo [C] y color error
- `--alert="mensaje"` - Mensaje de alerta con prefijo [A] y color warning
- `--emergency="mensaje"` - Mensaje de emergencia con prefijo [E] y color error

Todos los comandos soportan opciones adicionales como `--color`, `--align`, etc.

#### 🎭 Componentes Visuales

Nuevos componentes para interfaces CLI mejoradas:

- `--header="texto"` - Encabezado con opciones de alineación y color
- `--separator` - Separador visual con opciones `--char` y `--color`
- `--breadcrumbs --items="Item1,Item2,Item3"` - Breadcrumbs navegables
- `--bar --current=N --total=M` - Barra de progreso visual
- `--menu --header-text="texto" --options="Op1,Op2,Op3"` - Menú de opciones
- `--question="pregunta"` - Pregunta interactiva con color configurable
- `--confirm="mensaje"` - Confirmación con estilo
- `--animate="texto"` - Texto animado con prefijo configurable

#### 🖨️ Aurora.Printer API

Nueva API de alto nivel para impresión directa, basada en `Aegis.Printer`:

- **`Aurora.Printer`** - API unificada que delega a módulos especializados
  - `Aurora.Printer.Basic` - Mensajes básicos y tipos predefinidos (success, error, warning, etc.)
  - `Aurora.Printer.Components` - Componentes UI (headers, separators, breadcrumbs, progress bars)
  - `Aurora.Printer.Tables` - Formateo de tablas
- **Integración con CLI**: El CLI ahora usa `Aurora.Printer` cuando no se usa el flag `--raw`
- **Modo raw**: Con `--raw`, el CLI devuelve el string ANSI crudo para procesamiento externo
- **Compatibilidad**: Mantiene compatibilidad con el comportamiento anterior mientras añade nuevas capacidades

#### 📊 Tablas Avanzadas

Mejoras significativas en el sistema de tablas:

**Nuevo formato de argumentos dinámicos:**
- `--headers-color="color1;color2;..."` - Colores por celda de header (separados por punto y coma)
- `--headers-bold="true;false;..."` - Efecto bold por celda de header
- `--headers-<effect>="..."` - Cualquier efecto por celda: `--headers-italic`, `--headers-underline`, etc.
- `--row-color="color1;color2;..."` - Colores para todas las filas (template)
- `--row-<effect>="..."` - Efectos para todas las filas: `--row-bold`, `--row-italic`, etc.
- `--row-0-color="color1;color2;..."` - Colores específicos para fila 0
- `--row-1-color="color1;color2;..."` - Colores específicos para fila 1, etc.
- `--row-<n>-<effect>="..."` - Efectos específicos por fila: `--row-0-bold`, `--row-1-italic`, etc.

**Características:**
- Normalización automática de tamaño de filas (relleno o truncado)
- Cálculo automático del número máximo de columnas
- Soporte para headers y filas con diferentes longitudes
- Compatibilidad con formato legacy mantenida

#### 📥 Soporte JSON Completo

- **Entrada desde stdin**: `echo '{"command":"success","message":"Done!"}' | ./aurora --stdin`
- **Entrada desde parámetro**: `./aurora --json='{"command":"error","message":"Failed"}'`
- **Comandos soportados vía JSON**:
  - `message`, `success`, `error`, `warning`, `info`, `debug`, `notice`, `critical`, `alert`, `emergency`
  - `table` - Con `headers` y `rows` (arrays o strings)
  - `header`, `separator`, `breadcrumbs`, `bar`, `menu`, `question`, `confirm`, `animate`
- **Opciones en JSON**: Campo `options` para pasar opciones adicionales
- **Manejo de errores**: Validación y mensajes de error claros para JSON inválido

#### 🎯 Mejoras en Text Chunks

- **Agrupación inteligente**: Los bloques de texto se agrupan con sus efectos y colores correspondientes
- **Preservación de orden**: El orden de los argumentos se preserva para aplicar efectos correctamente
- **Manipulación de colores**: Soporte mejorado para `--lighten`, `--darken`, `--inverted` por bloque
- **Fallback seguro**: Si `argv` no está disponible, usa comportamiento legacy compatible

### 🔧 Mejoras

- **Cobertura de tests**: Aumentada de ~77% a 90%+
  - Tests completos para CLI (88%+)
  - Tests para casos edge y funciones privadas
  - Tests para conversión de colores
  - Tests para todos los componentes visuales
  - Tests para JSON input/output
- **Arquitectura mejorada**: Nueva API `Aurora.Printer` que separa la lógica de impresión de la lógica de formateo
  - Separación clara entre formateo (`Aurora.Format`) e impresión (`Aurora.Printer`)
  - Reutilización de código: `Aurora.Printer` usa `Aurora.Format` internamente
  - API consistente y fácil de usar para impresión directa
- **Manejo de errores**: Mejorado significativamente
  - Validación de parámetros en conversión de colores
  - Manejo robusto de JSON inválido o malformado
  - Mensajes de error más descriptivos
  - Manejo de casos edge en parsing de argumentos
- **Parsing de argumentos**: Sistema mejorado
  - Extracción de argumentos dinámicos antes de OptionParser
  - Soporte para argumentos con formato `--row-<n>-<attr>=value`
  - Parsing robusto de valores CSV y separados por punto y coma
  - Validación de formatos de color (hex, tuple, nombre)
- **Documentación**: Completamente actualizada
  - README con ejemplos de todas las nuevas características
  - Moduledoc actualizado en todos los módulos
  - Ejemplos prácticos para cada funcionalidad
  - Guía de migración implícita en ejemplos
- **Rendimiento**: Optimizaciones
  - Procesamiento más eficiente de tablas grandes
  - Reducción de operaciones redundantes en formateo
  - Mejor manejo de memoria en conversiones de color

### 🐛 Correcciones

- **Efectos por bloque**: Corregido bug donde los efectos se aplicaban a todos los chunks en lugar de solo al bloque correspondiente
- **Argumentos dinámicos**: Mejorado el manejo de argumentos con formato `--headers-*` y `--row-*`
- **Parsing de ARGB**: Corregido parsing de tuplas ARGB con 4 elementos
- **Normalización de filas**: Corregido comportamiento cuando filas tienen diferentes longitudes
- **Modo raw en macOS**: Corregido escape de ANSI codes en modo raw (ahora no se escapan)
- **IO.puts vs IO.write**: Corregido uso correcto según modo (raw vs normal)

### 📚 Documentación

- **README.md**: Completamente actualizado
  - Nueva sección de características v2.0.0
  - Ejemplos de todas las nuevas funcionalidades
  - Guía de uso de modo raw
  - Ejemplos de JSON input
  - Ejemplos de componentes visuales
- **CHANGELOG.md**: Actualizado con todos los cambios
- **Moduledoc**: Actualizado en todos los módulos principales
  - `Aurora.CLI`: Documentación completa de todas las opciones
  - `Aurora.Format`: Ejemplos actualizados
  - `Aurora.Color`: Documentación de conversiones
- **Ejemplos de código**: Añadidos en documentación inline

### 🔄 Cambios que Requieren Atención

- **Comportamiento por defecto**: Aurora ahora imprime automáticamente. Para obtener solo el string, usar `--raw`
- **Efectos**: Los efectos ahora son por bloque, no globales. Para aplicar efectos a todos los chunks, repetir el flag después de cada `--text`
- **Compatibilidad**: El formato legacy de tablas sigue funcionando, pero se recomienda migrar al nuevo formato con argumentos dinámicos

## [1.0.5] - 2025-10-11

### 🎉 Versión Estable Actual

Actualización para integración con Proyecto Ypsilon.

### 🏗️ Arquitectura Base

- **Nivel 1A en Proyecto Ypsilon**
- **LIBRERÍA BASE SIN DEPENDENCIAS**
- **Sin dependencias circulares**
- **Completa independencia de otros niveles**

### 🎨 Sistema de Colores y Formateo

#### Funciones Principales
- `Aurora.format/2` - Formateo con color, align, bold y más
- `Aurora.colorize/2` - Solo aplicar color
- `Aurora.stylize/2` - Aplicar efectos ANSI (individuales/múltiples)

#### Datos Estructurados
- `Aurora.json/2` - JSON formateado
- `Aurora.chunks/1` - Crear múltiples chunks
- `Aurora.format_chunks/2` - Formatear lista de chunks

#### Utilidades
- `Aurora.clean/1` - Quitar códigos ANSI
- `Aurora.text_length/1` - Longitud sin ANSI
- `Aurora.colors/0` - Listar colores
- `Aurora.effects/0` - Listar efectos

### 🔧 Módulos Especializados

#### Formato Avanzado
- `Aurora.Format` - Control total del formateo
- `Aurora.Color` - Manejo avanzado de colores
- `Aurora.Effects` - Control de efectos
- `Aurora.Convert` - Utilidades de conversión
- `Aurora.Ensure` - Garantía de tipos
- `Aurora.Normalize` - Normalización de datos

### 📦 Estructuras de Datos

#### ChunkText
```elixir
%Aurora.Structs.ChunkText{
  text: String.t(),           # Texto (requerido)
  color: %ColorInfo{},        # Color opcional
  effects: %EffectInfo{},     # Efectos opcionales
  pos_x: integer(),           # Posición horizontal
  pos_y: integer()            # Posición vertical
}
```

#### ColorInfo
```elixir
%Aurora.Structs.ColorInfo{
  name: atom(),               # Nombre del color
  hex: String.t(),           # Código hexadecimal
  inverted: boolean()         # Si está invertido
}
```

#### FormatInfo
```elixir
%Aurora.Structs.FormatInfo{
  chunks: [%ChunkText{}],     # Lista de chunks (requerido)
  default_color: %ColorInfo{}, # Color por defecto
  align: atom(),              # Alineación (:left, :right, :center, :justify, :center_block)
  manual_tabs: integer(),    # Indentación manual (-1 = automática)
  add_line: atom(),           # Saltos de línea (:before, :after, :both, :none)
  animation: String.t(),      # Prefijo de animación
  mode: atom()                # Modo de renderizado (:normal, :table, :raw)
}
```

#### EffectInfo
```elixir
%Aurora.Structs.EffectInfo{
  bold: boolean(),            # Negrita
  italic: boolean(),          # Cursiva
  underline: boolean(),       # Subrayado
  dim: boolean(),             # Atenuado
  blink: boolean(),           # Parpadeante
  reverse: boolean(),          # Invertido
  hidden: boolean(),          # Oculto
  strikethrough: boolean()    # Tachado
}
```

### 🧪 Pruebas

- Suite completa de pruebas unitarias
- Cobertura de código > 93%
- Tests de integración para todas las funciones principales
- Tests para casos de borde y errores

### 📚 Documentación

- README.md completo con ejemplos prácticos
- Documentación en línea para todas las funciones públicas
- Guía de uso para diferentes escenarios
- Integración con `mix docs`

## [1.0.4] - 2025-10-10

### 🚀 Versión Anterior Estable

Versión estable anterior que servirá como base para la nueva arquitectura.

### 🛠️ Funcionalidad Principal

- Sistema de colores ANSI completo
- Formateo de texto con alineación
- Efectos de texto (negrita, cursiva, subrayado)
- Gradientes de color
- Soporte para JSON formateado
- Utilidades de limpieza de códigos ANSI

## Versión 1.0.3 (2025-09-26)

### 🔧 Refactoring

- Refactor y fix de Effects. Actualizacion de documentación

## Versión 1.0.2 (2025-09-25)

### 🔧 Refactoring

- Refactor nombres de funciones de "Ensure"

## Versión 1.0.1 (2025-09-24)

### 

- Refactor de "Convert" porque en algunas ocasiones da problemas de compilacion

## Versión 1.0.0 (2025-09-24)

### 

- Publicacion libreria

[Unreleased]: https://github.com/usuario/aurora/compare/v1.0.5...HEAD
[1.0.5]: https://github.com/usuario/aurora/releases/tag/v1.0.5
[1.0.4]: https://github.com/usuario/aurora/releases/tag/v1.0.4