ansimax 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,158 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.2.0] — Phase 2 complete: animated, eased & conic gradients
+
+Minor release closing the **gradient engine roadmap (Phase 2)** with three
+long-awaited capabilities. All additions are fully backwards-compatible —
+existing `gradient()` calls work identically.
+
+### Added — Easing curves
+
+`gradient()` now accepts an `easing` option to control how colors are
+distributed along the text. Five built-in curves plus custom functions:
+
+```ts
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'ease-in' });
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'ease-out' });
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'ease-in-out' });
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: 'cubic-bezier' });
+
+// Or pass a custom EasingFn (t → eased t, both in [0,1])
+gradient('hello world', ['#ff0000', '#0000ff'], { easing: (t) => t * t * t });
+```
+
+- `linear` — even distribution (default, identical to pre-1.2.0 behavior)
+- `ease-in` — concentrates colors at the end (quadratic)
+- `ease-out` — concentrates colors at the start (quadratic)
+- `ease-in-out` — slow at both ends, fast in middle
+- `cubic-bezier` — CSS-style `ease` curve (Newton-Raphson approximated)
+- Out-of-range custom easings are clamped to `[0, 1]` automatically
+
+### Added — Phase offset (flowing colors)
+
+`gradient()` now accepts a `phase` parameter `[0, 1)` that shifts the
+gradient along the text. Combined with an animation loop, this produces
+a flowing color effect:
+
+```ts
+gradient('hello', ['#ff0000', '#0000ff'], { phase: 0.5 });
+// negative values wrap forward; NaN/Infinity falls back to 0
+```
+
+### Added — `animateGradient()` API
+
+High-level API for animated gradients with proper lifecycle management:
+
+```ts
+import { animateGradient } from 'ansimax';
+
+const ctrl = animateGradient('Loading...', ['#ff79c6', '#bd93f9', '#8be9fd'], {
+  duration: 2000,
+  fps: 30,
+  direction: 'forward',  // or 'reverse'
+  infinite: true,
+});
+
+// Later
+ctrl.stop();
+// Or via AbortController
+const abort = new AbortController();
+animateGradient('hi', stops, { signal: abort.signal });
+abort.abort();
+```
+
+Returns an `AnimateGradientController` with `.stop()` and `.done` (Promise).
+Supports `AbortSignal`, custom render via `onFrame`, fps cap at 60,
+and direction reversal.
+
+### Added — Conic gradients
+
+`gradientRect()` now supports `style: 'conic'` for radial sweeps around
+the center point:
+
+```ts
+import { gradientRect } from 'ansimax';
+
+console.log(gradientRect({
+  width: 30, height: 15,
+  colors: ['#ff0000', '#00ff00', '#0000ff', '#ff0000'],
+  style: 'conic',
+  startAngle: 0,  // rotation in degrees
+  dither: 'bayer',
+}));
+```
+
+- `startAngle` (degrees) rotates the sweep
+- Non-finite `startAngle` falls back to `0`
+- Compatible with all existing options (`dither`, `braille`, `width`, `height`)
+
+### Added — New exports
+
+- `animateGradient` — function
+- `AnimateGradientOptions` / `AnimateGradientController` — types
+- `EasingName` — union type of built-in curve names
+- `EasingFn` — `(t: number) => number` curve type
+
+### Notes
+
+- All 1848 + 30 new tests pass.
+- Backwards-compatible: existing `gradient()` calls work identically.
+- No new runtime dependencies.
+- Phase 2 of the [roadmap](README.md#%EF%B8%8F-roadmap) is now **fully complete**.
+
+---
+
+## [1.1.2] — maturity & robustness
+
+Patch release focused on maturity: better error semantics, defensive
+defaults, and cleaner type re-exports. No API breaking changes — every
+1.1.1 program runs identically.
+
+### Fixed
+
+- **CI: `jest.config.js` syntax error.** The config file used `export default {}`
+  (ESM syntax), which crashed in Node CommonJS context — including in
+  GitHub Actions runners. Fixed by switching to `module.exports = {}` to
+  match `useESM: false` in the ts-jest configuration. Tests now run
+  correctly across Linux, macOS, and Windows runners.
+
+### Improved
+
+- **`process.setMaxListeners` defensive bump.** Ansimax modules
+  (`animations`, `frames`, `loaders`, `utils/ansi`) each register
+  `SIGINT` / `SIGTERM` / `exit` handlers for crash-safe cursor
+  restoration. With Node's default cap of 10, hot-reload setups
+  (Vite HMR, nodemon, ts-node-dev) could occasionally emit
+  `MaxListenersExceededWarning`. We now bump the cap to 20 on first
+  install — silently and safely, only if the current limit is lower.
+  Production apps unaffected.
+- **Uniform `TypeError` for theme validation.** `themes.register()`
+  now throws `TypeError` for any structural / type issue (missing
+  fields, non-string `name`, invalid hex), matching the rest of the
+  validation surface. Previously it threw a mix of `Error` and
+  `TypeError`, which made `try / catch` filtering inconsistent.
+- **`themes.use()` throws `RangeError`** for unknown theme names
+  (was `Error`). `RangeError` better reflects "value out of allowed
+  set" semantics — same standard library convention as `Array(-1)`.
+  Error message now also says "Available themes:" instead of
+  "Available:" for clarity.
+- **Cleaner type re-exports in the barrel.** Added a header comment
+  explaining the legacy aliases (`stripAnsiColors`, `stripAnsiCodes`)
+  and recommending `stripAnsi` for new code. Version string in the
+  barrel header updated from the stale `v1.0.0` to `v1.1.2`.
+
+### Notes
+
+- All 1848 tests pass; 4 new tests cover the error-type guarantees.
+- The error-type changes are technically observable via `instanceof`
+  checks, but `RangeError` and `TypeError` both extend `Error`, so any
+  `catch (e: Error)` block keeps working. We classify this as a
+  non-breaking quality-of-life improvement.
+- No new dependencies — still zero runtime deps.
+
+---
+
 ## [1.1.1] — bug fixes + improved examples
 
 Patch release with two bug fixes from real-world testing of v1.1.0, plus

package/README.es.md

@@ -7,7 +7,7 @@
 _Colores • Gradientes • Animaciones • ASCII Art • Pixel Art • Árboles • Componentes • Temas_
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
-[![npm](https://img.shields.io/badge/npm-v1.1.1-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.2.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg?style=flat-square)](tsconfig.json)
 [![Coverage](https://img.shields.io/badge/coverage-98%25-brightgreen.svg?style=flat-square)](#testing)
 [![Tests](https://img.shields.io/badge/tests-1700%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -50,14 +50,14 @@ npm install ansimax
 ```
 
 ```ts
-import { color, gradient, ascii, loader } from 'ansimax';
+import { color, gradient, ascii, loader, sleep } from 'ansimax';
 
 console.log(ascii.banner('hola', {
   colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9', '#8be9fd']),
 }));
 
 const stop = loader.spin('Construyendo proyecto', { color: '#bd93f9' });
-await algunaTareaAsync();
+await sleep(1500);
 stop('Build completado', true);
 ```
 
@@ -123,14 +123,14 @@ yarn add ansimax
 ## ⚡ Ejemplo en 30 segundos
 
 ```ts
-import { color, gradient, loader, ascii } from 'ansimax';
+import { color, gradient, loader, ascii, sleep } from 'ansimax';
 
 console.log(ascii.banner('deploy', {
   colorFn: (t) => gradient(t, ['#ff6b6b', '#feca57', '#48dbfb']),
 }));
 
 const stop = loader.spin('Construyendo proyecto', { color: '#bd93f9' });
-await algunaTareaAsync();
+await sleep(1500);             // simula trabajo asíncrono
 stop('Build completado', true);  // ✓ + color de éxito
 
 console.log(color.green('✓') + ' Listo en ' + color.bold('1.4s'));
@@ -187,12 +187,66 @@ console.log(themes.primary('primary de cyberpunk'));
 <img src="media/colors.png" alt="Colores y gradientes" />
 
 ```ts
-import { color, gradient } from 'ansimax';
+import { color, gradient, rainbow } from 'ansimax';
 
-color.red('rojo');   color.green('verde');  color.blue('azul');
-color.bold(texto);   color.italic(texto);    color.underline(texto);
-gradient('fuego a océano', ['#ff6b6b', '#feca57', '#48dbfb']);
-color.rainbow('preset rainbow integrado');
+// Colores básicos
+console.log(color.red('rojo'), color.green('verde'), color.blue('azul'));
+
+// Modificadores de estilo
+console.log(color.bold('negrita'), color.italic('itálica'), color.underline('subrayado'));
+
+// Gradiente multi-stop
+console.log(gradient('fuego a océano', ['#ff6b6b', '#feca57', '#48dbfb']));
+
+// Preset rainbow integrado
+console.log(rainbow('preset rainbow integrado'));
+```
+
+### Gradientes animados (v1.2.0)
+
+```ts
+import { animateGradient, sleep } from 'ansimax';
+
+// Animación de flujo de color — corre hasta llamar stop()
+const ctrl = animateGradient('Cargando...', ['#ff79c6', '#bd93f9', '#8be9fd'], {
+  duration: 2000,    // ms por ciclo
+  fps: 30,
+  direction: 'forward',  // o 'reverse'
+});
+
+await sleep(3000);
+ctrl.stop();
+```
+
+### Curvas de interpolación (v1.2.0)
+
+```ts
+import { gradient } from 'ansimax';
+
+// Cinco easings built-in + soporte para funciones personalizadas
+gradient('hola mundo', stops, { easing: 'linear' });
+gradient('hola mundo', stops, { easing: 'ease-in' });
+gradient('hola mundo', stops, { easing: 'ease-out' });
+gradient('hola mundo', stops, { easing: 'ease-in-out' });
+gradient('hola mundo', stops, { easing: 'cubic-bezier' });
+
+// O tu propia función de easing (t → t suavizado, ambos en [0,1])
+gradient('hola mundo', stops, { easing: (t) => t * t * t });
+```
+
+### Gradientes cónicos (v1.2.0)
+
+```ts
+import { gradientRect } from 'ansimax';
+
+// Barrido radial alrededor del centro — rueda arcoíris
+console.log(gradientRect({
+  width: 30, height: 15,
+  colors: ['#ff0000', '#ffff00', '#00ff00', '#00ffff', '#0000ff', '#ff00ff', '#ff0000'],
+  style: 'conic',
+  startAngle: 0,   // ángulo de rotación en grados
+  dither: 'bayer',
+}));
 ```
 
 ### ASCII Art
@@ -202,13 +256,13 @@ color.rainbow('preset rainbow integrado');
 ```ts
 import { ascii, gradient } from 'ansimax';
 
-ascii.banner('HOLA', {
+console.log(ascii.banner('HOLA', {
   font: 'big',
   align: 'center',
   colorFn: (t) => gradient(t, ['#ff79c6', '#bd93f9']),
-});
+}));
 
-ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' });
+console.log(ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' }));
 ```
 
 ### Árboles
@@ -235,7 +289,7 @@ console.log(proyecto.render({
 <img src="media/pixel_art.png" alt="Pixel art" />
 
 ```ts
-import { images, createCanvas, gradientRect } from 'ansimax';
+import { images, createCanvas, gradientRect, SPRITES } from 'ansimax';
 
 // Sprite integrado
 console.log(images.sprite('heart'));
@@ -251,7 +305,8 @@ console.log(gradientRect({
 const c = createCanvas(40, 10);
 c.fill({ r: 18, g: 18, b: 38 });
 c.drawCircle(20, 5, 4, { r: 255, g: 200, b: 0 }, true);
-c.drawSprite(2, 2, images.sprites.star!.pixels);
+const starSprite = SPRITES.star;
+if (starSprite) c.drawSprite(2, 2, starSprite.pixels);
 c.print();
 ```
 
@@ -262,15 +317,15 @@ c.print();
 ```ts
 import { components, color } from 'ansimax';
 
-components.table([
+console.log(components.table([
   ['Módulo',     'Estado',                'Cobertura'],
   ['colors',     color.green('● listo'),  '100%'],
   ['animations', color.green('● listo'),  '100%'],
   ['loaders',    color.green('● listo'),  '100%'],
-], { borderStyle: 'rounded' });
+], { borderStyle: 'rounded' }));
 
-components.badge('VERSION', 'v1.1.1');
-components.badge('BUILD',   'passing');
+console.log(components.badge('VERSION', 'v1.2.0'));
+console.log(components.badge('BUILD',   'passing'));
 ```
 
 ### Timeline
@@ -278,22 +333,24 @@ components.badge('BUILD',   'passing');
 <img src="media/timeline.png" alt="Timeline" />
 
 ```ts
-components.timeline([
+import { components } from 'ansimax';
+
+console.log(components.timeline([
   { label: 'Init del proyecto', done: true,  time: '10:00' },
   { label: 'Pipeline de build', done: true,  time: '10:15' },
   { label: 'Correr tests',      done: false, time: '10:32' },
   { label: 'Deploy a npm',      done: false },
-]);
+]));
 ```
 
 ### Loaders y Progreso
 
 ```ts
-import { loader } from 'ansimax';
+import { loader, sleep } from 'ansimax';
 
 // Spinner con éxito/fallo
 const stop = loader.spin('Cargando...', { color: '#bd93f9' });
-await tarea();
+await sleep(1500);
 stop('¡Listo!', true);   // ✓ ícono verde
 
 // Barra de progreso animada
@@ -303,18 +360,22 @@ await loader.progressAnimate(100, 'Descargando', {
 
 // Tareas jerárquicas con ejecución paralela
 await loader.tasks([
-  { text: 'Build', fn: async () => build(), subtasks: [
-    { text: 'TypeScript', fn: async () => tsc() },
-    { text: 'Bundle',     fn: async () => bundle() },
-  ]},
-  { text: 'Test',  fn: async () => test() },
+  {
+    text: 'Build',
+    fn: async () => await sleep(500),
+    subtasks: [
+      { text: 'TypeScript', fn: async () => await sleep(800) },
+      { text: 'Bundle',     fn: async () => await sleep(600) },
+    ],
+  },
+  { text: 'Test', fn: async () => await sleep(700) },
 ], { parallel: true });
 ```
 
 ### Animaciones
 
 ```ts
-import { animate, gradient } from 'ansimax';
+import { animate, gradient, sleep } from 'ansimax';
 
 await animate.typewriter('Bienvenido al wizard de deployment...', {
   speed: 30,
@@ -325,9 +386,9 @@ await animate.fadeIn('Carga completa', { duration: 600 });
 
 // Carrera de pasos contra timeout — nunca se cuelga
 await animate.parallel([
-  async () => await checkNetwork(),
-  async () => await checkDatabase(),
-  async () => await checkAuth(),
+  async () => await sleep(500),   // simulación de chequeo de red
+  async () => await sleep(700),   // simulación de chequeo de base de datos
+  async () => await sleep(400),   // simulación de chequeo de auth
 ], { timeout: 5000 });
 ```
 
@@ -340,7 +401,7 @@ import { themes, createTheme } from 'ansimax';
 
 // Temas built-in
 themes.use('dracula');
-themes.primary('hola');
+console.log(themes.primary('hola'));
 
 // Escuchar cambios
 const off = themes.onChange((nuevo, anterior) => {
@@ -350,7 +411,27 @@ const off = themes.onChange((nuevo, anterior) => {
 // Multi-tenant: cada instancia totalmente aislada
 const tenantA = createTheme('nord');
 const tenantB = createTheme('matrix');
-tenantA.register('custom', miDef);  // no se filtra a tenantB
+
+// Definir un tema personalizado y registrarlo SÓLO en tenantA
+tenantA.register('custom', {
+  name: 'Custom',
+  primary:   '#ff5e5e',
+  secondary: '#5e5eff',
+  accent:    '#5eff5e',
+  success:   '#10b981',
+  warning:   '#fbbf24',
+  error:     '#ef4444',
+  info:      '#06b6d4',
+  muted:     '#6b7280',
+  bg:        '#1e293b',
+  surface:   '#334155',
+  text:      '#f1f5f9',
+  gradient:  ['#ff5e5e', '#5eff5e', '#5e5eff'],
+});
+
+console.log('tenantA incluye custom?', tenantA.list().includes('custom'));
+console.log('tenantB incluye custom?', tenantB.list().includes('custom'));
+//                                     ↑ false — aislamiento total
 ```
 
 ---
@@ -421,11 +502,11 @@ const off = onConfigKeyChange('theme', (nuevo, anterior) => {
 
 // Override temporal + restauración automática al completar o lanzar
 await withConfig({ animationSpeed: 'fast' }, async () => {
-  await correrDemo();
+  // ...tu código en modo fast aquí...
 });
 
 // Modo strict captura typos en config
-configure({ unknwnKey: 'x' }, { strict: true });  // lanza RangeError
+// configure({ unknwnKey: 'x' }, { strict: true });  // lanza RangeError
 ```
 
 ---
@@ -453,9 +534,9 @@ El roadmap apunta intencionalmente — y busca superar — gaps que ni siquiera
 - [x] Gradientes a ángulo arbitrario
 - [x] Dithering Bayer 4×4 para transiciones tonales suaves
 - [x] UX single-stop (comportamiento estilo CSS)
-- [ ] **Gradientes animados** (flujo de color en el tiempo, loops infinitos)
-- [ ] **Curvas de interpolación** (linear / ease-in / ease-out / cubic-bezier)
-- [ ] **Gradientes cónicos** (barrido radial)
+- [x] **Gradientes animados** — flujo de color en el tiempo con `animateGradient()` (v1.2.0)
+- [x] **Curvas de interpolación** — `linear` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier` / personalizado (v1.2.0)
+- [x] **Gradientes cónicos** — barrido radial con `style: 'conic'` (v1.2.0)
 
 ### 🟡 Fase 3 — Motor ASCII
 - [x] Fuentes de bloque (`big`, `small`)
@@ -645,6 +726,35 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.2.0 — Fase 2 completa: gradientes animados, easing y cónicos
+
+Release minor que cierra el roadmap del motor de gradientes con tres features potentes:
+
+- 🌊 **`animateGradient()`** — flujo de color en el tiempo con ciclo de vida apropiado (Promise, signal, fps, direction)
+- 📐 **Curvas de interpolación** — `linear` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier` / funciones personalizadas
+- ⭕ **Gradientes cónicos** — `gradientRect({ style: 'conic', startAngle })` para barridos radiales
+
+```ts
+import { animateGradient } from 'ansimax';
+
+const ctrl = animateGradient('Cargando...', ['#ff79c6', '#bd93f9', '#8be9fd']);
+await sleep(3000);
+ctrl.stop();
+```
+
+Totalmente retrocompatible — todo programa 1.1.x corre idénticamente.
+
+### v1.1.2 — Madurez y robustez
+
+Release patch enfocado en refinamientos de calidad — sin cambios en la API.
+
+- 🛡️ **Bump defensivo de `process.setMaxListeners`** — previene `MaxListenersExceededWarning` en setups con HMR / nodemon / ts-node-dev donde los módulos de ansimax re-registran handlers de restauración de cursor
+- 🧪 **`TypeError` uniforme para validación de themes** — `themes.register()` ahora arroja consistentemente `TypeError` para errores estructurales / de tipo (antes era mezcla de `Error` y `TypeError`)
+- 🎯 **`themes.use()` arroja `RangeError`** para nombres de tema desconocidos (antes `Error`) — mejor match semántico con "valor fuera del set permitido"
+- 📝 **Re-exports más limpios en el barrel** — comentario de header ahora documenta aliases legacy y recomienda nombres canónicos
+
+Drop-in replacement para `1.1.1`.
+
 ### v1.1.1 — Fixes de bugs + ejemplos limpios
 
 Release patch que arregla dos bugs encontrados en testing real de v1.1.0, más una carpeta de ejemplos refrescada.
@@ -750,4 +860,4 @@ Ansimax está licenciada bajo **Apache License, Version 2.0** — una licencia p
 
 Si Ansimax te ayuda a hacer mejores CLIs, ¡dale ⭐ en [GitHub](https://github.com/Brashkie/ansimax)!
 
-</div>
+</div>