ansimax 1.1.0 → 1.1.2

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.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.1.2-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)
@@ -20,6 +20,27 @@ _Colores • Gradientes • Animaciones • ASCII Art • Pixel Art • Árboles
 
 ---
 
+<div align="center">
+
+### 🎬 Vista previa
+
+<table>
+  <tr>
+    <td align="center">
+      <strong>Animaciones</strong><br/>
+      <img src="media/animations.gif" alt="Demo de animaciones de Ansimax" width="420"/>
+    </td>
+    <td align="center">
+      <strong>Loaders</strong><br/>
+      <img src="media/loaders.gif" alt="Demo de loaders de Ansimax" width="420"/>
+    </td>
+  </tr>
+</table>
+
+</div>
+
+---
+
 ## 🌟 ¿Qué es Ansimax?
 
 Ansimax es una **librería de renderizado todo-en-uno** para construir interfaces de terminal hermosas en Node.js. Un solo paquete reemplaza un stack de más de 8 dependencias — colores, gradientes, ASCII art, spinners, barras de progreso, tablas, menús, árboles, temas, pixel art — combinadas en una única API coherente de TypeScript con **cero dependencias en runtime**.
@@ -29,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);
 ```
 
@@ -102,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'));
@@ -166,12 +187,19 @@ 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';
+
+// Colores básicos
+console.log(color.red('rojo'), color.green('verde'), color.blue('azul'));
 
-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');
+// 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'));
 ```
 
 ### ASCII Art
@@ -181,13 +209,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
@@ -214,7 +242,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'));
@@ -230,7 +258,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();
 ```
 
@@ -241,15 +270,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.0');
-components.badge('BUILD',   'passing');
+console.log(components.badge('VERSION', 'v1.1.2'));
+console.log(components.badge('BUILD',   'passing'));
 ```
 
 ### Timeline
@@ -257,22 +286,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
@@ -282,18 +313,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,
@@ -304,9 +339,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 });
 ```
 
@@ -319,7 +354,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) => {
@@ -329,28 +364,60 @@ 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
 ```
 
 ---
 
 ## 📚 Ejemplos
 
-Siete ejemplos de calidad de producción se publican en el paquete npm y son ejecutables directamente. Los encuentras en [`/examples`](./examples) después de instalar:
+Once ejemplos de calidad de producción se publican en el paquete npm y son ejecutables directamente. Los encuentras en [`/examples`](./examples) después de instalar:
 
 | Archivo | Qué demuestra |
 |---|---|
-| `trees-basic.ts` | Ejemplo mínimo de árboles — API builder + algoritmos |
-| `01-cli-installer.ts` | Instalador estilo npm-create — banner + tareas jerárquicas + íconos de estado + caja resumen |
-| `02-live-dashboard.ts` | Dashboard en tiempo real — `frames.live` + tabla de servicios + barras con gradiente + `onResize` + limpieza SIGINT |
-| `03-pixel-art-game.ts` | Sprite de cohete rebotando — canvas + alpha blending + gradiente + contador de FPS + loop con corrección de drift |
-| `04-interactive-deploy.ts` | Menú + multi-select + `loader.multi` + `createTheme` + `onConfigChange` |
-| `05-tree-visualizations.ts` | Árboles de filesystem + dependencias + JSON + decisión (`walk` + `measure` extra) |
-| `06-everything-together.ts` | Showcase completo — cada módulo ejercitado en un demo cohesivo |
+| `01-quick-smoke.ts` | Test rápido de humo — verifica que cada import principal funciona |
+| `02-colors-gradients.ts` | Toda función de color, tipos de gradiente, presets, compose, API chain |
+| `03-ascii-banners.ts` | Banners (`big`/`small`), 6 estilos de caja, divisores, compositor de logos |
+| `04-trees.ts` | Tree builder + API data-plana, 4 estilos, palettes, algoritmos (walk/find/map/filter) |
+| `05-components.ts` | Tablas, badges, status, secciones, columnas, timelines, barras de progreso |
+| `06-pixel-art.ts` | Sprites, canvas personalizado, gradient rects con dither, transforms (flip/rotate) |
+| `07-animations.ts` | typewriter, fadeIn/Out, slide, pulse, wave, glitch, reveal |
+| `08-loaders.ts` | Estilos de spinner, progreso animado, tareas jerárquicas, cuenta regresiva |
+| `09-themes.ts` | Los 8 temas integrados, listeners, registro de temas personalizados, aislamiento por instancia |
+| `10-everything.ts` | Showcase completo — cada módulo ejercitado en un demo cohesivo |
+| `all-in-one.mjs` | Demo completo en **ESM** (JS puro con `import`) — sin necesidad de TypeScript |
+| `all-in-one.cjs` | Demo completo en **CommonJS** (JS puro con `require`) — sin necesidad de TypeScript |
 
 Ejecuta cualquier ejemplo con:
 ```bash
-npx tsx examples/06-everything-together.ts
+# Ejemplos en TypeScript
+npx tsx examples/10-everything.ts
+
+# JS puro — ESM
+node examples/all-in-one.mjs
+
+# JS puro — CommonJS
+node examples/all-in-one.cjs
 ```
 
 ---
@@ -388,11 +455,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
 ```
 
 ---
@@ -604,7 +671,7 @@ ansimax/
 │   ├── trees/          Builder de árboles + algoritmos
 │   ├── utils/          Primitivas ANSI + helpers
 │   └── configure.ts    Config global + subscribers
-├── examples/           7 ejemplos de calidad de producción
+├── examples/           10 ejemplos (TS) + 2 (JS — ESM y CJS) — todas las funciones cubiertas
 └── __tests__/          16 test suites, 1700+ tests
 ```
 
@@ -612,6 +679,28 @@ ansimax/
 
 ## 📝 Changelog
 
+### 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.
+
+- 🐛 **Fix de crash en `box()`** con `padding: { x, y }` — ahora cae graciosamente al default para padding no-numérico (también maneja NaN, Infinity, strings)
+- 🐛 **Fix de leak de cursor en `components.menu()`** al salir abruptamente (Ctrl+C, SIGTERM) — handlers de cleanup de emergencia ahora restauran el cursor incluso cuando el proceso se mata mid-menu
+- 📚 **Nuevos ejemplos** — 10 ejemplos en TypeScript + 2 variantes en JS puro (`all-in-one.mjs` para ESM, `all-in-one.cjs` para CommonJS)
+- 📖 **READMEs actualizados** — GIFs de preview en el header, GIF de showcase completo en el footer
+
+Sin cambios en la API — drop-in replacement para `1.1.0`.
+
 ### v1.1.0 — Hardening exhaustivo + nuevas features
 
 Una pasada masiva de robustez sobre todo módulo, más un nuevo módulo `trees`. **100% retrocompatible** — toda API existente funciona idéntica.
@@ -676,6 +765,18 @@ Si Ansimax te ahorra tiempo, por favor dale estrella al repo en [GitHub](https:/
 
 ---
 
+## 🎬 Showcase completo
+
+<div align="center">
+
+<img src="media/all-ansimax.gif" alt="Showcase completo de Ansimax — todo en acción" width="720"/>
+
+_Todas las funciones en acción — typewriter, gradientes, banners ASCII, árboles, tablas, spinners, temas y pixel art_
+
+</div>
+
+---
+
 ## 📜 Licencia
 
 [Apache License 2.0](LICENSE) © 2026 Brashkie
@@ -694,4 +795,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>