ansimax 1.3.3 → 1.3.5

package/CHANGELOG.md

@@ -3,6 +3,285 @@
 All notable changes to **ansimax** are documented in this file.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [1.3.5] — Mathematical color science + cleanup
+
+Patch release focused on mathematical depth: perceptually-uniform color
+spaces (Oklab/HSL), comprehensive easing library, and removing duplicate
+defensive patterns. **Zero breaking changes** — `lerpColor` and
+`gradientColor` accept a new optional `space` parameter that defaults to
+`'rgb'` (the previous behavior).
+
+### Added — Perceptually-uniform color spaces
+
+**Oklab** — modern perceptual color space. Interpolating in Oklab produces
+smoother, more natural-looking gradients than naive RGB:
+
+```js
+import { lerpColor, mixColors, gradientStops } from 'ansimax';
+
+const red  = { r: 255, g: 0, b: 0   };
+const blue = { r: 0,   g: 0, b: 255 };
+
+lerpColor(red, blue, 0.5);            // → { r: 128, g: 0,  b: 128 } (RGB midpoint — muddy)
+lerpColor(red, blue, 0.5, 'oklab');   // → { r: 140, g: 83, b: 162 } (perceptual midpoint — vibrant)
+
+// Or with hex inputs:
+mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
+
+// Multi-stop gradients:
+gradientStops('#ff0000', '#0000ff', 5, 'oklab');
+```
+
+**HSL** — useful for hue rotation and color manipulation:
+
+```js
+import { rgbToHsl, hslToRgb, lerpColor } from 'ansimax';
+
+const hsl = rgbToHsl({ r: 255, g: 100, b: 50 });   // → { h: 12, s: 1, l: 0.598 }
+
+// hslToRgb wraps hue automatically:
+hslToRgb({ h: -120, s: 1, l: 0.5 });   // → { r: 0, g: 0, b: 255 }
+hslToRgb({ h: 720,  s: 1, l: 0.5 });   // → { r: 255, g: 0, b: 0 }
+
+// Interpolation through HSL takes the shorter arc on the color wheel:
+lerpColor(red, blue, 0.5, 'hsl');
+```
+
+### Added — `easings` library (Robert Penner library)
+
+Comprehensive easing curve library:
+
+```js
+import { easings, resolveEasingByName, animate } from 'ansimax';
+
+// All curves: in/out/inOut variants of:
+// quad, cubic, quart, quint, sine, expo, circ, back, elastic, bounce
+// Plus linear.
+
+await animate.countUp(0, 1000, {
+  duration: 2000,
+  easing: easings.easeOutBounce,    // bouncing ball deceleration
+});
+
+// Resolve by name:
+const fn = resolveEasingByName('easeInElastic');
+```
+
+### Added — Color utilities
+
+**`mixColors(a, b, t, space?)`** — semantic alias accepting hex or RGB:
+
+```js
+mixColors('#ff0000', { r: 0, g: 0, b: 255 }, 0.5, 'oklab');
+```
+
+**`quantizeColor(color, levels)`** — palette reduction (posterize effect):
+
+```js
+quantizeColor({ r: 100, g: 150, b: 200 }, 4);
+// Snaps each channel to nearest of [0, 85, 170, 255] → 64-color palette
+```
+
+### Added — Numeric helpers
+
+**`isFiniteNumber(n)`** — type guard, previously internal:
+
+```js
+isFiniteNumber(42);         // → true
+isFiniteNumber(NaN);        // → false
+isFiniteNumber('5');        // → false
+```
+
+**`safeInt(value, fallback?, min?, max?)`** — consolidates the
+`Math.max(0, Math.floor(Number(x) || 0))` pattern that appeared 25+
+times across the codebase:
+
+```js
+safeInt('abc')                 // → 0
+safeInt(3.7)                   // → 3
+safeInt(NaN, 50)               // → 50  (fallback)
+safeInt(500, 0, 0, 100)        // → 100 (clamped to max)
+```
+
+**`clampByte(v)`** — previously private, now exported.
+
+### Improved — `gradientStops` accepts `space` parameter
+
+```js
+gradientStops('#ff0000', '#0000ff', 5);          // RGB (default, fast)
+gradientStops('#ff0000', '#0000ff', 5, 'oklab'); // perceptually uniform
+```
+
+### Improved — Code cleanliness
+
+- Replaced internal duplicate `typeof n === 'number' && Number.isFinite(n)`
+  checks with `isFiniteNumber()` calls
+- `gradientColor` now uses `isFiniteNumber` instead of inline check
+
+### Improved — Tests
+
+- `+18` tests for color spaces (rgbToHsl, hslToRgb, rgbToOklab, oklabToRgb)
+- `+9` tests for `lerpColor` with spaces + `mixColors`
+- `+6` tests for `quantizeColor`
+- `+10` tests for numeric helpers (`isFiniteNumber`, `safeInt`, `clampByte`)
+- `+30` tests for `easings` library (every curve + endpoint preservation)
+- `+5` tests for `resolveEasingByName`
+- `+4` tests for v1.3.5 barrel re-exports
+
+Total: **+82 tests** added.
+
+### Notes
+
+- No runtime dependencies — still zero
+- **No breaking changes** — `lerpColor(a, b, t)` defaults to `'rgb'` and
+  produces identical output to v1.3.4
+- Oklab math validated via roundtrip identity tests (±1 byte tolerance
+  for floating-point through linear sRGB intermediate)
+- All easing curves verified to map `f(0) ≈ 0` and `f(1) ≈ 1`
+
+---
+
+## [1.3.4] — Feature additions across animations, configure, utils
+
+Patch release adding small but useful features to several modules. No
+breaking changes — every addition is opt-in.
+
+### Added — `animations` module
+
+**`animate.shake(text, opts)`** — horizontal tremble effect for errors or alerts:
+
+```js
+import { animate } from 'ansimax';
+
+await animate.shake('Connection failed', {
+  times: 5,
+  intensity: 2,
+  interval: 50,
+});
+```
+
+**`animate.countUp(from, to, opts)`** — numeric animation for counters:
+
+```js
+await animate.countUp(0, 100, {
+  duration: 1500,
+  decimals: 0,
+  format: (n) => `$${n.toLocaleString()}`,
+  easing: (t) => 1 - (1 - t) ** 3,   // ease-out cubic
+});
+// Animates from "$0" → "$100" over 1.5 seconds
+```
+
+Both functions support the standard animation pattern: `signal`, `reducedMotion`,
+`onFrame`, `onDone`, `onAbort`.
+
+### Added — `configure` module
+
+**`setConfigValue(key, value)`** — single-key shortcut:
+
+```js
+import { setConfigValue } from 'ansimax';
+
+setConfigValue('theme', 'dracula');
+setConfigValue('animationSpeed', 'fast');
+// equivalent to: configure({ theme: 'dracula' })
+```
+
+**`subscribeConfig(listener)`** — alias for `onConfigChange` matching the
+naming convention used by `themes.onChange`:
+
+```js
+import { subscribeConfig } from 'ansimax';
+
+const unsubscribe = subscribeConfig((newCfg, oldCfg) => {
+  console.log('Config changed:', newCfg);
+});
+```
+
+### Added — `utils/ansi` module
+
+**`hyperlink(url, label?)`** — OSC 8 escape sequence for clickable terminal links:
+
+```js
+import { hyperlink } from 'ansimax';
+
+console.log(`Visit ${hyperlink('https://github.com/Brashkie/ansimax', 'the repo')}`);
+console.log(`Email: ${hyperlink('mailto:hi@example.com')}`);
+```
+
+Supported terminals: VS Code, iTerm2, WezTerm, Kitty, Hyper, Alacritty, modern
+Windows Terminal. Terminals without support just show the label text.
+
+**`clearLine()`** — convenience for clearing current line + carriage return:
+
+```js
+import { clearLine } from 'ansimax';
+
+for (let i = 0; i <= 100; i++) {
+  process.stdout.write(clearLine() + `Progress: ${i}%`);
+  await sleep(30);
+}
+```
+
+### Added — `utils/helpers` module
+
+**`gradientStops(start, end, count)`** — interpolate N hex stops between two colors:
+
+```js
+import { gradientStops } from 'ansimax';
+
+const stops = gradientStops('#ff0000', '#0000ff', 5);
+// → ['#ff0000', '#bf003f', '#7f007f', '#3f00bf', '#0000ff']
+```
+
+**`escapeForRegex(str)`** — escape regex meta-characters in user input:
+
+```js
+import { escapeForRegex } from 'ansimax';
+
+const userInput = 'hello.world+code';
+const re = new RegExp(escapeForRegex(userInput));
+// Matches the literal string, not as a regex pattern
+```
+
+**`measureBlock(block)`** — get dimensions of a multi-line string (ANSI-aware):
+
+```js
+import { measureBlock, ascii } from 'ansimax';
+
+const box = ascii.box('Hello world!');
+const { width, height } = measureBlock(box);
+// → { width: 15, height: 3 }
+```
+
+### Improved — `node-globals.d.ts`
+
+Added ambient declarations for `AsyncIterator`, `AsyncIterable`, `AsyncGenerator`,
+and `Symbol.asyncIterator`. Lets code using `for await...of` type-check without
+needing `@types/node` installed at consumer projects.
+
+### Improved — Tests
+
+- `+6` tests for `gradientStops`
+- `+5` tests for `escapeForRegex`
+- `+7` tests for `measureBlock`
+- `+5` tests for `hyperlink`
+- `+2` tests for `clearLine`
+- `+4` tests for `setConfigValue`
+- `+3` tests for `subscribeConfig`
+- `+5` tests for `animate.shake`
+- `+8` tests for `animate.countUp`
+
+Total: **+45 tests** across utils, ansi, configure, animations.
+
+### Notes
+
+- No runtime dependencies — still zero
+- No breaking changes — drop-in replacement for `1.3.3`
+- All new exports backward-compatible by default
+
+---
+
 ## [1.3.3] — Feature additions to panels, json, ascii
 
 Patch release adding new functionality to three modules. No breaking changes —

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.3-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.3.5-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)
@@ -478,7 +478,7 @@ console.log(components.table([
   ['loaders',    color.green('● listo'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.3.3'));
+console.log(components.badge('VERSION', 'v1.3.5'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -1065,6 +1065,64 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.3.5 — Color science matemático + limpieza
+
+Release patch enfocado en profundidad matemática y limpieza de código. Cero breaking changes:
+
+- 🎨 **Espacio de color Oklab** — `rgbToOklab` / `oklabToRgb`. Gradientes perceptualmente uniformes
+- 🌈 **Espacio de color HSL** — `rgbToHsl` / `hslToRgb`. Rotación de matiz, manipulación de color
+- 🎯 **`lerpColor` / `gradientColor` / `gradientStops`** ahora aceptan `space: 'rgb' | 'hsl' | 'oklab'` (default `'rgb'`, retro-compatible)
+- 🥄 **`mixColors(a, b, t, space)`** — alias semántico, acepta hex strings o RGB
+- 📐 **`quantizeColor(color, levels)`** — reducción de paleta (efecto posterize)
+- ⚡ **Librería `easings`** — set completo de Robert Penner (quad/cubic/quart/quint/sine/expo/circ/back/elastic/bounce en in/out/inOut)
+- 🧮 **`isFiniteNumber` + `safeInt` + `clampByte`** — helpers numéricos exportados (consolida 25+ patrones defensivos duplicados)
+- 🧪 **+82 tests** incluyendo validación de correctitud matemática
+
+```js
+import { lerpColor, easings, animate, mixColors } from 'ansimax';
+
+// Midpoint de gradiente perceptualmente uniforme
+mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
+// → { r: 140, g: 83, b: 162 } — magenta vibrante
+// (vs RGB naive: { r: 128, g: 0, b: 128 } — púrpura turbio)
+
+// Contador con animación bouncing
+await animate.countUp(0, 1000, {
+  duration: 2000,
+  easing: easings.easeOutBounce,
+});
+```
+
+Drop-in replacement para `1.3.4`.
+
+### v1.3.4 — Features para animations, configure, utils
+
+Release patch con features opt-in en varios módulos. Cero breaking changes:
+
+- 🎬 **`animate.shake(text, opts)`** — efecto tremor horizontal para errores
+- 🔢 **`animate.countUp(from, to, opts)`** — contadores numéricos animados con format/easing
+- ⚙️ **`setConfigValue(key, value)`** — atajo single-key + alias `subscribeConfig`
+- 🔗 **`hyperlink(url, label)`** — links clickables vía OSC 8 (VS Code, iTerm2, WezTerm, Kitty...)
+- 🧹 **`clearLine()`** — helper conveniente para render loops
+- 🎨 **`gradientStops(start, end, count)`** — N stops procedurales entre dos colores
+- 🛡️ **`escapeForRegex(str)`** — escapa input de usuario para regex literals
+- 📏 **`measureBlock(block)`** — dimensiones ANSI-aware de texto multi-línea
+- 📐 **`node-globals.d.ts`** — añadidos tipos `AsyncIterator`/`AsyncIterable`/`AsyncGenerator`
+- 🧪 **+45 tests** entre animations, configure, utils
+
+```js
+import { animate, hyperlink } from 'ansimax';
+
+await animate.countUp(0, 1000, {
+  duration: 1500,
+  format: (n) => `$${n.toLocaleString()}`,
+});
+
+console.log(`Ver ${hyperlink('https://npmjs.com/ansimax', 'la página de npm')}`);
+```
+
+Drop-in replacement para `1.3.3`.
+
 ### v1.3.3 — Features para panels, json, ascii
 
 Release patch con nuevas features opt-in. Cero breaking changes:
@@ -1458,4 +1516,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>

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.3-cb3837.svg?style=flat-square)](https://www.npmjs.com/package/ansimax)
+[![npm](https://img.shields.io/badge/npm-v1.3.5-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)
@@ -478,7 +478,7 @@ console.log(components.table([
   ['loaders',    color.green('● ready'),  '100%'],
 ], { borderStyle: 'rounded' }));
 
-console.log(components.badge('VERSION', 'v1.3.3'));
+console.log(components.badge('VERSION', 'v1.3.5'));
 console.log(components.badge('BUILD',   'passing'));
 ```
 
@@ -1065,6 +1065,64 @@ ansimax/
 
 ## 📝 Changelog
 
+### v1.3.5 — Mathematical color science + cleanup
+
+Patch release focused on math depth and code cleanliness. Zero breaking changes:
+
+- 🎨 **Oklab color space** — `rgbToOklab` / `oklabToRgb`. Perceptually uniform gradients
+- 🌈 **HSL color space** — `rgbToHsl` / `hslToRgb`. Hue rotation, color manipulation
+- 🎯 **`lerpColor` / `gradientColor` / `gradientStops`** all accept `space: 'rgb' | 'hsl' | 'oklab'` (default `'rgb'`, retro-compatible)
+- 🥄 **`mixColors(a, b, t, space)`** — semantic alias, accepts hex strings or RGB
+- 📐 **`quantizeColor(color, levels)`** — palette reduction (posterize effect)
+- ⚡ **`easings` library** — full Robert Penner set (quad/cubic/quart/quint/sine/expo/circ/back/elastic/bounce in/out/inOut)
+- 🧮 **`isFiniteNumber` + `safeInt` + `clampByte`** — exported numeric helpers (consolidates 25+ duplicate defensive patterns)
+- 🧪 **+82 tests** including math correctness validation
+
+```js
+import { lerpColor, easings, animate, mixColors } from 'ansimax';
+
+// Perceptually-uniform gradient midpoint
+mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
+// → { r: 140, g: 83, b: 162 } — vibrant magenta
+// (vs naive RGB: { r: 128, g: 0, b: 128 } — muddy purple)
+
+// Bouncing counter animation
+await animate.countUp(0, 1000, {
+  duration: 2000,
+  easing: easings.easeOutBounce,
+});
+```
+
+Drop-in replacement for `1.3.4`.
+
+### v1.3.4 — Feature additions across animations, configure, utils
+
+Patch release with opt-in additions to several modules. Zero breaking changes:
+
+- 🎬 **`animate.shake(text, opts)`** — horizontal tremble effect for error feedback
+- 🔢 **`animate.countUp(from, to, opts)`** — animated numeric counters with format/easing
+- ⚙️ **`setConfigValue(key, value)`** — single-key config shortcut + `subscribeConfig` alias
+- 🔗 **`hyperlink(url, label)`** — OSC 8 clickable terminal links (VS Code, iTerm2, WezTerm, Kitty...)
+- 🧹 **`clearLine()`** — convenience helper for render loops
+- 🎨 **`gradientStops(start, end, count)`** — procedural N-color stops
+- 🛡️ **`escapeForRegex(str)`** — escape user input for regex literals
+- 📏 **`measureBlock(block)`** — get ANSI-aware dimensions of multi-line text
+- 📐 **`node-globals.d.ts`** — added `AsyncIterator`/`AsyncIterable`/`AsyncGenerator` ambient types
+- 🧪 **+45 tests** across animations, configure, utils
+
+```js
+import { animate, hyperlink } from 'ansimax';
+
+await animate.countUp(0, 1000, {
+  duration: 1500,
+  format: (n) => `$${n.toLocaleString()}`,
+});
+
+console.log(`See ${hyperlink('https://npmjs.com/ansimax', 'the npm page')}`);
+```
+
+Drop-in replacement for `1.3.3`.
+
 ### v1.3.3 — Features for panels, json, ascii
 
 Patch release with new opt-in features. Zero breaking changes:
@@ -1458,4 +1516,4 @@ Ansimax is licensed under the **Apache License, Version 2.0** — a permissive l
 
 If Ansimax helps you ship better CLIs, give it a ⭐ on [GitHub](https://github.com/Brashkie/ansimax)!
 
-</div>
+</div>