ansimax 1.3.0 → 1.3.2

package/CHANGELOG.md

@@ -3,6 +3,165 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.3.2] — Documentation polish for frames + images
+
+Patch release improving JSDoc + IntelliSense coverage for the two largest
+modules that were under-documented. No code changes — pure DX upgrade.
+
+### Improved — JSDoc with runnable examples
+
+**`frames` module (previously 0 examples → now 17):**
+- `frames.play` — 5 examples (basic loop, play-once, abortable, pause/resume, custom onFrame)
+- `frames.generate` — 3 examples (pulsing dot, progress bar, error tolerance)
+- `frames.live` — 3 examples (reactive counter, async data stream, FPS clamping)
+- `frames.morph` — 3 examples (basic, custom charset, chained sequences)
+- `frames.presets` — 3 examples (loadingBar, pulse, wave with custom rendering)
+
+**`images` module (previously 0 examples → now 18):**
+- `renderPixelArt` — 4 examples (heart sprite, scaling, background, sprite lookup)
+- `gradientRect` — 7 examples (horizontal, vertical, diagonal, radial, conic, dithered, braille)
+- `createCanvas` — 4 examples (basic scene, animated frame, sprite composition, resize)
+- `SPRITES` — 3 examples (render single, list all, compose on canvas)
+
+### Why this matters
+
+Before v1.3.2, users hovering `frames.play(...)` in their editor saw just
+the signature `(frames: string[], opts?: PlayOptions): PlayController`.
+Now they see 5 runnable examples showing pause/resume patterns, AbortSignal
+integration, custom rendering callbacks — significantly reducing the
+"what do I pass here?" friction for new users.
+
+### Notes
+
+- No code changes — pure documentation
+- No runtime dependencies — still zero
+- No new tests required — existing test coverage unchanged
+- Drop-in replacement for `1.3.1`
+
+---
+
+## [1.3.1] — Polish for panels + json
+
+Patch release improving the two modules introduced in v1.3.0 — adds layout
+helpers, JSON readability options, and tests. No breaking changes.
+
+### Added — `panels.center(block, opts)`
+
+Center a multi-line block horizontally (and optionally vertically) within
+a fixed width/height. Useful for centering boxes, banners, or any pre-rendered
+block in a known terminal width.
+
+```js
+import { panels, ascii } from 'ansimax';
+
+// Horizontal centering only
+console.log(panels.center('Hello!', { width: 30 }));
+//   "            Hello!            "
+
+// Vertical too — content fits in 5 rows
+console.log(panels.center('X', { width: 5, height: 5, align: 'center' }));
+
+// Combine with box for a centered card
+console.log(panels.center(ascii.box('Hello'), { width: 80 }));
+```
+
+Exported as `centerBlock` from the main barrel (to avoid colliding with the
+existing `center` text helper). The namespaced form `panels.center` works
+identically.
+
+### Added — `panels.frame(block, opts)`
+
+Lighter alternative to `ascii.box`: draws only top/bottom decorative rules
+(not full sides). Supports a centered title, padding, and custom characters.
+
+```js
+import { panels } from 'ansimax';
+
+// Simple rules
+console.log(panels.frame('Hello world!'));
+// ─────────────
+// Hello world!
+// ─────────────
+
+// With title + padding
+console.log(panels.frame('Body content\nMore content', {
+  title: 'Header',
+  padding: 1,
+}));
+// ───── Header ─────
+//
+//  Body content
+//  More content
+//
+// ──────────────────
+
+// Custom decoration chars
+console.log(panels.frame('Important!', {
+  topChar: '═',
+  padding: 2,
+}));
+```
+
+### Added — `json.pretty` option `sortKeys`
+
+Sort object keys alphabetically for deterministic output. Useful for diffs,
+snapshots, and visual scanning of large objects.
+
+```js
+import { json } from 'ansimax';
+
+console.log(json.pretty({ zebra: 1, apple: 2, mango: 3 }, { sortKeys: true }));
+// {
+//   "apple": 2,
+//   "mango": 3,
+//   "zebra": 1
+// }
+```
+
+Recursive — applies to all nested objects. Default `false` (preserves
+insertion order).
+
+### Added — `json.pretty` option `inlineArrayMaxLength`
+
+Arrays of primitives now render on a single line when their rendered length
+is short enough (default threshold: 60 visible characters). This improves
+readability significantly for typical configs:
+
+```js
+// Before v1.3.1:
+{
+  "tags": [
+    "frontend",
+    "react",
+    "typescript"
+  ]
+}
+
+// In v1.3.1 (default behavior):
+{
+  "tags": ["frontend", "react", "typescript"]
+}
+```
+
+Arrays containing objects/arrays never inline regardless of length. Set
+`inlineArrayMaxLength: 0` to restore the v1.3.0 always-expand behavior.
+
+### Improved — Tests
+
+- `+11` tests for `panels.center` + `panels.frame`
+- `+15` tests for `json.pretty` `sortKeys` + `inlineArrayMaxLength`
+- Total tests: 2,000+ → **~2,026** across 18 suites
+
+### Notes
+
+- No runtime dependencies — still zero
+- No breaking changes — drop-in replacement for `1.3.0`
+- `panels.center` is exposed as `centerBlock` at the top level to avoid
+  conflict with the existing `center` text helper; both `panels.center` and
+  `centerBlock` reference the same function
+
+---
+
 ## [1.3.0] — Phase 4 progress: Panels + JSON pretty-print
 
 Minor release adding **split layout primitives** and **JSON pretty-printing**.

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.3.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.3.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-2000%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -215,6 +215,8 @@ console.log(rainbow('preset rainbow integrado'));
 
 ### Gradientes animados (v1.2.0)
 
+<img src="media/animated_gradients.png" alt="Vista previa de gradientes animados" />
+
 ```js
 import { animateGradient, sleep } from 'ansimax';
 
@@ -273,6 +275,8 @@ console.log(gradientRect({
 
 ### Gradientes reusables (v1.2.3)
 
+<img src="media/reusable_gradients.png" alt="Vista previa de gradientes reusables" />
+
 ```js
 import { createGradient, reverseGradient, ascii } from 'ansimax';
 
@@ -319,6 +323,8 @@ console.log(ascii.box('¡Caja arcoiris!', { padding: 1, borderStyle: 'rounded' }
 
 ### Imagen → ASCII (v1.2.5)
 
+<img src="media/image_to_ascii.png" alt="Vista previa de Image-to-ASCII" />
+
 ```js
 import { ascii } from 'ansimax';
 import sharp from 'sharp';
@@ -371,6 +377,8 @@ console.log(ascii.fromImage(pixels, {
 
 ### Fuentes Figlet (v1.2.5)
 
+<img src="media/figlet_fonts.png" alt="Vista previa de fuentes figlet" />
+
 ```js
 import { readFileSync } from 'node:fs';
 import { parseFiglet, ascii, gradient } from 'ansimax';
@@ -445,7 +453,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.3.0'));
+console.log(components.badge('VERSION', 'v1.3.2'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -466,6 +474,8 @@ console.log(components.timeline([
 
 ### Loaders y Progreso
 
+<img src="media/loaders.png" alt="Vista previa de loaders y barras de progreso" />
+
 ```js
 import { loader, sleep } from 'ansimax';
 
@@ -495,6 +505,8 @@ await loader.tasks([
 
 ### Animaciones
 
+<img src="media/animations.png" alt="Vista previa de animaciones" />
+
 ```js
 import { animate, gradient, sleep } from 'ansimax';
 
@@ -557,6 +569,8 @@ console.log('tenantB incluye custom?', tenantB.list().includes('custom'));
 
 ### Panels — Layouts divididos (v1.3.0)
 
+<img src="media/panels.png" alt="Vista previa de panels y layouts divididos" />
+
 ```js
 import { panels, ascii } from 'ansimax';
 
@@ -586,6 +600,8 @@ console.log(panels.hsplit([
 
 ### JSON Pretty-print (v1.3.0)
 
+<img src="media/json_pretty.png" alt="Vista previa de JSON pretty-print" />
+
 ```js
 import { json } from 'ansimax';
 
@@ -612,6 +628,22 @@ console.log(json.pretty(obj));   // → "self": [Circular]
 
 ---
 
+## 📖 Documentación
+
+La carpeta [`docs/`](./docs) contiene ejemplos completos para cada módulo:
+
+| Documento | Descripción |
+|---|---|
+| [`docs/README.md`](./docs/README.md) | Índice de documentación — empieza aquí |
+| [`docs/examples-ts.md`](./docs/examples-ts.md) | 33 ejemplos en TypeScript (3 por módulo × 11 módulos) |
+| [`docs/examples-mjs.md`](./docs/examples-mjs.md) | 33 ejemplos en JavaScript ESM |
+| [`docs/examples-cjs.md`](./docs/examples-cjs.md) | 33 ejemplos en JavaScript CommonJS |
+| [`docs/showcase.md`](./docs/showcase.md) | App completa que combina todos los módulos |
+
+Cada ejemplo es **copy-paste ejecutable** con escenarios realistas de complejidad media — no solo one-liners.
+
+---
+
 ## 📚 Ejemplos
 
 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:
@@ -1006,6 +1038,58 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.3.2 — Pulido de documentación para frames + images
+
+Release patch con cobertura JSDoc + IntelliSense significativamente mejorada:
+
+- 📝 **Módulo `frames`** — `play`, `generate`, `live`, `morph`, `presets` ahora tienen JSDoc completo con 17 ejemplos ejecutables
+- 📝 **Módulo `images`** — `renderPixelArt`, `gradientRect`, `createCanvas`, `SPRITES` ahora tienen 18 ejemplos ejecutables
+- 🎯 **Total**: +35 nuevos bloques `@example` visibles en tu editor
+
+```js
+// Pasando el cursor sobre frames.play() en VS Code ahora muestra patrones de uso:
+import { frames } from 'ansimax';
+
+await frames.play(myFrames, {
+  interval: 80,
+  loop: true,
+  signal: ctrl.signal,
+  onFrame: (f, i) => color.cyan(`[${i}] ${f}`),
+}).promise;
+```
+
+Release puramente de documentación — cero cambios en código, API o tests.
+Drop-in replacement para `1.3.1`.
+
+### v1.3.1 — Pulido de panels + json
+
+Release patch que mejora los módulos de v1.3.0 con quality-of-life:
+
+- 🎯 **`panels.center(block, opts)`** — centra un block horizontalmente (y opcionalmente verticalmente) en un ancho conocido
+- 🖼️ **`panels.frame(block, opts)`** — alternativa más ligera a `ascii.box`: solo top/bottom con title + padding opcionales
+- 📋 **`json.pretty` opción `sortKeys`** — orden alfabético de keys para diffs deterministas
+- 📐 **`json.pretty` opción `inlineArrayMaxLength`** — arrays cortos de primitivos ahora se renderizan como `[1, 2, 3]` en una línea (threshold default: 60 chars)
+- 🧪 **+26 tests** entre panels + json
+
+```js
+import { panels, json } from 'ansimax';
+
+// Centrar un box dentro de la terminal
+console.log(panels.center(ascii.box('Hello'), { width: 80 }));
+
+// Frame decorativo más ligero
+console.log(panels.frame('Body', { title: 'Header', padding: 1 }));
+
+// Sorted, con inline arrays
+console.log(json.pretty({ zebra: [1, 2, 3], apple: 'A' }, { sortKeys: true }));
+// {
+//   "apple": "A",
+//   "zebra": [1, 2, 3]
+// }
+```
+
+Drop-in replacement para `1.3.0`.
+
 ### v1.3.0 — Avance Fase 4: Panels + JSON pretty-print
 
 Release minor que añade dos nuevos módulos top-level — split layouts y pretty-print de JSON:

package/README.md

@@ -7,7 +7,7 @@
 _Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • Components • Themes_
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg?style=flat-square)](LICENSE)
-[![npm](https://img.shields.io/badge/npm-v1.3.0-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.3.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-2000%2B%20passing-brightgreen.svg?style=flat-square)](#testing)
@@ -215,6 +215,8 @@ console.log(rainbow('built-in rainbow preset'));
 
 ### Animated Gradients (v1.2.0)
 
+<img src="media/animated_gradients.png" alt="Animated gradients preview" />
+
 ```js
 import { animateGradient, sleep } from 'ansimax';
 
@@ -273,6 +275,8 @@ console.log(gradientRect({
 
 ### Reusable Gradients (v1.2.3)
 
+<img src="media/reusable_gradients.png" alt="Reusable gradients preview" />
+
 ```js
 import { createGradient, reverseGradient, ascii } from 'ansimax';
 
@@ -319,6 +323,8 @@ console.log(ascii.box('Rainbow box!', { padding: 1, borderStyle: 'rounded' }));
 
 ### Image → ASCII (v1.2.5)
 
+<img src="media/image_to_ascii.png" alt="Image-to-ASCII preview" />
+
 ```js
 import { ascii } from 'ansimax';
 import sharp from 'sharp';
@@ -371,6 +377,8 @@ console.log(ascii.fromImage(pixels, {
 
 ### Figlet Fonts (v1.2.5)
 
+<img src="media/figlet_fonts.png" alt="Figlet fonts preview" />
+
 ```js
 import { readFileSync } from 'node:fs';
 import { parseFiglet, ascii, gradient } from 'ansimax';
@@ -445,7 +453,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.3.0'));
+console.log(components.badge('VERSION', 'v1.3.2'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -466,6 +474,8 @@ console.log(components.timeline([
 
 ### Loaders & Progress
 
+<img src="media/loaders.png" alt="Loaders and progress bars preview" />
+
 ```js
 import { loader, sleep } from 'ansimax';
 
@@ -495,6 +505,8 @@ await loader.tasks([
 
 ### Animations
 
+<img src="media/animations.png" alt="Animations preview" />
+
 ```js
 import { animate, gradient, sleep } from 'ansimax';
 
@@ -557,6 +569,8 @@ console.log('tenantB themes include custom?', tenantB.list().includes('custom'))
 
 ### Panels — Split Layouts (v1.3.0)
 
+<img src="media/panels.png" alt="Panels and split layouts preview" />
+
 ```js
 import { panels, ascii } from 'ansimax';
 
@@ -586,6 +600,8 @@ console.log(panels.hsplit([
 
 ### JSON Pretty-print (v1.3.0)
 
+<img src="media/json_pretty.png" alt="JSON pretty-print preview" />
+
 ```js
 import { json } from 'ansimax';
 
@@ -612,6 +628,22 @@ console.log(json.pretty(obj));   // → "self": [Circular]
 
 ---
 
+## 📖 Documentation
+
+The [`docs/`](./docs) folder contains comprehensive examples for every module:
+
+| Document | Description |
+|---|---|
+| [`docs/README.md`](./docs/README.md) | Documentation index — start here |
+| [`docs/examples-ts.md`](./docs/examples-ts.md) | 33 TypeScript examples (3 per module × 11 modules) |
+| [`docs/examples-mjs.md`](./docs/examples-mjs.md) | 33 JavaScript ESM examples |
+| [`docs/examples-cjs.md`](./docs/examples-cjs.md) | 33 JavaScript CommonJS examples |
+| [`docs/showcase.md`](./docs/showcase.md) | Complete demo app combining every module |
+
+Every example is **copy-paste runnable** with realistic, mid-complexity scenarios — not just one-liners.
+
+---
+
 ## 📚 Examples
 
 Eleven production-grade examples ship in the npm package and are runnable directly. Find them in [`/examples`](./examples) once you install:
@@ -1006,6 +1038,58 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.3.2 — Documentation polish for frames + images
+
+Patch release with significantly improved JSDoc + IntelliSense coverage:
+
+- 📝 **`frames` module** — `play`, `generate`, `live`, `morph`, `presets` now have full JSDoc with 17 runnable examples
+- 📝 **`images` module** — `renderPixelArt`, `gradientRect`, `createCanvas`, `SPRITES` now have 18 runnable examples
+- 🎯 **Total**: +35 new `@example` blocks visible in your editor
+
+```js
+// Hovering frames.play() in VS Code now shows usage patterns:
+import { frames } from 'ansimax';
+
+await frames.play(myFrames, {
+  interval: 80,
+  loop: true,
+  signal: ctrl.signal,
+  onFrame: (f, i) => color.cyan(`[${i}] ${f}`),
+}).promise;
+```
+
+Pure documentation release — no code, API, or test changes.
+Drop-in replacement for `1.3.1`.
+
+### v1.3.1 — Polish for panels + json
+
+Patch release improving the modules from v1.3.0 with quality-of-life additions:
+
+- 🎯 **`panels.center(block, opts)`** — center a block horizontally (and optionally vertically) in a known width
+- 🖼️ **`panels.frame(block, opts)`** — lighter alternative to `ascii.box`: top/bottom rules only, with optional title + padding
+- 📋 **`json.pretty` option `sortKeys`** — alphabetic key order for deterministic diffs
+- 📐 **`json.pretty` option `inlineArrayMaxLength`** — short arrays of primitives now render as `[1, 2, 3]` on one line (default threshold: 60 chars)
+- 🧪 **+26 tests** across panels + json modules
+
+```js
+import { panels, json } from 'ansimax';
+
+// Center a box inside the terminal
+console.log(panels.center(ascii.box('Hello'), { width: 80 }));
+
+// Lighter decorative frame
+console.log(panels.frame('Body', { title: 'Header', padding: 1 }));
+
+// Sorted, with inline arrays
+console.log(json.pretty({ zebra: [1, 2, 3], apple: 'A' }, { sortKeys: true }));
+// {
+//   "apple": "A",
+//   "zebra": [1, 2, 3]
+// }
+```
+
+Drop-in replacement for `1.3.0`.
+
 ### v1.3.0 — Phase 4 progress: Panels + JSON pretty-print
 
 Minor release adding two new top-level modules — split layouts and JSON pretty-printing: