ansimax 1.3.4 → 1.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +185 -0
- package/README.es.md +40 -2
- package/README.md +40 -2
- package/dist/index.d.mts +188 -8
- package/dist/index.d.ts +188 -8
- package/dist/index.js +294 -49
- package/dist/index.mjs +283 -49
- package/examples/all-in-one.cjs +1 -1
- package/examples/all-in-one.mjs +1 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -3,6 +3,191 @@
|
|
|
3
3
|
All notable changes to **ansimax** are documented in this file.
|
|
4
4
|
This project follows [Semantic Versioning](https://semver.org/).
|
|
5
5
|
|
|
6
|
+
## [1.3.6] — Branch coverage improvements
|
|
7
|
+
|
|
8
|
+
Maintenance release. Zero behavior changes — only adds tests covering
|
|
9
|
+
defensive branches and adjusts `istanbul ignore` comments where branches
|
|
10
|
+
are genuinely unreachable in normal usage.
|
|
11
|
+
|
|
12
|
+
### Improved — Tests
|
|
13
|
+
|
|
14
|
+
**panels (`+7` tests):**
|
|
15
|
+
- `vsplit` default `gap = 1` when option omitted
|
|
16
|
+
- `vsplit` handles columns of unequal heights (triggers `block[r] ?? ''` fallback)
|
|
17
|
+
- `centerBlock` default `align = 'center'` with `height` (vertical centering branch)
|
|
18
|
+
- `centerBlock` with explicit `align='start'` (alternative branch)
|
|
19
|
+
- `frame` fallback `'─'` when `topChar=''` or non-string
|
|
20
|
+
- `grid` default `columns = 1` when option omitted/undefined
|
|
21
|
+
|
|
22
|
+
**frames (`+7` tests):**
|
|
23
|
+
- `ensureString` handles `null`/`undefined` via `?? ''` fallback
|
|
24
|
+
- `presets.loadingBar` fallback `'░'` for invalid `empty` (`''` or non-string)
|
|
25
|
+
- `presets.ball` fallback `width = 20` for `NaN`/non-number input
|
|
26
|
+
- `presets.breathe` fallback `steps = 8` for `NaN`/non-number input
|
|
27
|
+
|
|
28
|
+
**loaders (`+5` tests):**
|
|
29
|
+
- `loader.bar` fallback `'░'` for invalid `emptyChar`
|
|
30
|
+
- `loader.spin` finalText with all three success states (`undefined`, `true`, `false`)
|
|
31
|
+
— exercises icon ternary chain branches
|
|
32
|
+
|
|
33
|
+
### Improved — `istanbul ignore` comments
|
|
34
|
+
|
|
35
|
+
Some `??` and conditional-spread branches are unreachable in real usage
|
|
36
|
+
(e.g. `frames[frame] ?? ''` after `frame = i % frames.length` with a non-empty
|
|
37
|
+
array). Marked with explanatory `istanbul ignore next` comments instead of
|
|
38
|
+
chasing coverage with synthetic tests:
|
|
39
|
+
|
|
40
|
+
- `loaders:376` — `frames[frame] ?? ''` (frame index always in bounds)
|
|
41
|
+
- `loaders:997` — second instance of `addOpts.color !== undefined` spread
|
|
42
|
+
|
|
43
|
+
Total: **+19 tests** added across panels, frames, loaders.
|
|
44
|
+
|
|
45
|
+
### Notes
|
|
46
|
+
|
|
47
|
+
- No runtime changes — drop-in replacement for `1.3.5`
|
|
48
|
+
- No new exports, no API surface changes
|
|
49
|
+
- Same `dist/` output as `1.3.5` would have produced
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## [1.3.5] — Mathematical color science + cleanup
|
|
54
|
+
|
|
55
|
+
Patch release focused on mathematical depth: perceptually-uniform color
|
|
56
|
+
spaces (Oklab/HSL), comprehensive easing library, and removing duplicate
|
|
57
|
+
defensive patterns. **Zero breaking changes** — `lerpColor` and
|
|
58
|
+
`gradientColor` accept a new optional `space` parameter that defaults to
|
|
59
|
+
`'rgb'` (the previous behavior).
|
|
60
|
+
|
|
61
|
+
### Added — Perceptually-uniform color spaces
|
|
62
|
+
|
|
63
|
+
**Oklab** — modern perceptual color space. Interpolating in Oklab produces
|
|
64
|
+
smoother, more natural-looking gradients than naive RGB:
|
|
65
|
+
|
|
66
|
+
```js
|
|
67
|
+
import { lerpColor, mixColors, gradientStops } from 'ansimax';
|
|
68
|
+
|
|
69
|
+
const red = { r: 255, g: 0, b: 0 };
|
|
70
|
+
const blue = { r: 0, g: 0, b: 255 };
|
|
71
|
+
|
|
72
|
+
lerpColor(red, blue, 0.5); // → { r: 128, g: 0, b: 128 } (RGB midpoint — muddy)
|
|
73
|
+
lerpColor(red, blue, 0.5, 'oklab'); // → { r: 140, g: 83, b: 162 } (perceptual midpoint — vibrant)
|
|
74
|
+
|
|
75
|
+
// Or with hex inputs:
|
|
76
|
+
mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
|
|
77
|
+
|
|
78
|
+
// Multi-stop gradients:
|
|
79
|
+
gradientStops('#ff0000', '#0000ff', 5, 'oklab');
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**HSL** — useful for hue rotation and color manipulation:
|
|
83
|
+
|
|
84
|
+
```js
|
|
85
|
+
import { rgbToHsl, hslToRgb, lerpColor } from 'ansimax';
|
|
86
|
+
|
|
87
|
+
const hsl = rgbToHsl({ r: 255, g: 100, b: 50 }); // → { h: 12, s: 1, l: 0.598 }
|
|
88
|
+
|
|
89
|
+
// hslToRgb wraps hue automatically:
|
|
90
|
+
hslToRgb({ h: -120, s: 1, l: 0.5 }); // → { r: 0, g: 0, b: 255 }
|
|
91
|
+
hslToRgb({ h: 720, s: 1, l: 0.5 }); // → { r: 255, g: 0, b: 0 }
|
|
92
|
+
|
|
93
|
+
// Interpolation through HSL takes the shorter arc on the color wheel:
|
|
94
|
+
lerpColor(red, blue, 0.5, 'hsl');
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
### Added — `easings` library (Robert Penner library)
|
|
98
|
+
|
|
99
|
+
Comprehensive easing curve library:
|
|
100
|
+
|
|
101
|
+
```js
|
|
102
|
+
import { easings, resolveEasingByName, animate } from 'ansimax';
|
|
103
|
+
|
|
104
|
+
// All curves: in/out/inOut variants of:
|
|
105
|
+
// quad, cubic, quart, quint, sine, expo, circ, back, elastic, bounce
|
|
106
|
+
// Plus linear.
|
|
107
|
+
|
|
108
|
+
await animate.countUp(0, 1000, {
|
|
109
|
+
duration: 2000,
|
|
110
|
+
easing: easings.easeOutBounce, // bouncing ball deceleration
|
|
111
|
+
});
|
|
112
|
+
|
|
113
|
+
// Resolve by name:
|
|
114
|
+
const fn = resolveEasingByName('easeInElastic');
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
### Added — Color utilities
|
|
118
|
+
|
|
119
|
+
**`mixColors(a, b, t, space?)`** — semantic alias accepting hex or RGB:
|
|
120
|
+
|
|
121
|
+
```js
|
|
122
|
+
mixColors('#ff0000', { r: 0, g: 0, b: 255 }, 0.5, 'oklab');
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
**`quantizeColor(color, levels)`** — palette reduction (posterize effect):
|
|
126
|
+
|
|
127
|
+
```js
|
|
128
|
+
quantizeColor({ r: 100, g: 150, b: 200 }, 4);
|
|
129
|
+
// Snaps each channel to nearest of [0, 85, 170, 255] → 64-color palette
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### Added — Numeric helpers
|
|
133
|
+
|
|
134
|
+
**`isFiniteNumber(n)`** — type guard, previously internal:
|
|
135
|
+
|
|
136
|
+
```js
|
|
137
|
+
isFiniteNumber(42); // → true
|
|
138
|
+
isFiniteNumber(NaN); // → false
|
|
139
|
+
isFiniteNumber('5'); // → false
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
**`safeInt(value, fallback?, min?, max?)`** — consolidates the
|
|
143
|
+
`Math.max(0, Math.floor(Number(x) || 0))` pattern that appeared 25+
|
|
144
|
+
times across the codebase:
|
|
145
|
+
|
|
146
|
+
```js
|
|
147
|
+
safeInt('abc') // → 0
|
|
148
|
+
safeInt(3.7) // → 3
|
|
149
|
+
safeInt(NaN, 50) // → 50 (fallback)
|
|
150
|
+
safeInt(500, 0, 0, 100) // → 100 (clamped to max)
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**`clampByte(v)`** — previously private, now exported.
|
|
154
|
+
|
|
155
|
+
### Improved — `gradientStops` accepts `space` parameter
|
|
156
|
+
|
|
157
|
+
```js
|
|
158
|
+
gradientStops('#ff0000', '#0000ff', 5); // RGB (default, fast)
|
|
159
|
+
gradientStops('#ff0000', '#0000ff', 5, 'oklab'); // perceptually uniform
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### Improved — Code cleanliness
|
|
163
|
+
|
|
164
|
+
- Replaced internal duplicate `typeof n === 'number' && Number.isFinite(n)`
|
|
165
|
+
checks with `isFiniteNumber()` calls
|
|
166
|
+
- `gradientColor` now uses `isFiniteNumber` instead of inline check
|
|
167
|
+
|
|
168
|
+
### Improved — Tests
|
|
169
|
+
|
|
170
|
+
- `+18` tests for color spaces (rgbToHsl, hslToRgb, rgbToOklab, oklabToRgb)
|
|
171
|
+
- `+9` tests for `lerpColor` with spaces + `mixColors`
|
|
172
|
+
- `+6` tests for `quantizeColor`
|
|
173
|
+
- `+10` tests for numeric helpers (`isFiniteNumber`, `safeInt`, `clampByte`)
|
|
174
|
+
- `+30` tests for `easings` library (every curve + endpoint preservation)
|
|
175
|
+
- `+5` tests for `resolveEasingByName`
|
|
176
|
+
- `+4` tests for v1.3.5 barrel re-exports
|
|
177
|
+
|
|
178
|
+
Total: **+82 tests** added.
|
|
179
|
+
|
|
180
|
+
### Notes
|
|
181
|
+
|
|
182
|
+
- No runtime dependencies — still zero
|
|
183
|
+
- **No breaking changes** — `lerpColor(a, b, t)` defaults to `'rgb'` and
|
|
184
|
+
produces identical output to v1.3.4
|
|
185
|
+
- Oklab math validated via roundtrip identity tests (±1 byte tolerance
|
|
186
|
+
for floating-point through linear sRGB intermediate)
|
|
187
|
+
- All easing curves verified to map `f(0) ≈ 0` and `f(1) ≈ 1`
|
|
188
|
+
|
|
189
|
+
---
|
|
190
|
+
|
|
6
191
|
## [1.3.4] — Feature additions across animations, configure, utils
|
|
7
192
|
|
|
8
193
|
Patch release adding small but useful features to several modules. No
|
package/README.es.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
_Colores • Gradientes • Animaciones • ASCII Art • Pixel Art • Árboles • Componentes • Temas_
|
|
8
8
|
|
|
9
9
|
[](LICENSE)
|
|
10
|
-
[](https://www.npmjs.com/package/ansimax)
|
|
11
11
|
[](tsconfig.json)
|
|
12
12
|
[](#testing)
|
|
13
13
|
[](#testing)
|
|
@@ -478,7 +478,7 @@ console.log(components.table([
|
|
|
478
478
|
['loaders', color.green('● listo'), '100%'],
|
|
479
479
|
], { borderStyle: 'rounded' }));
|
|
480
480
|
|
|
481
|
-
console.log(components.badge('VERSION', 'v1.3.
|
|
481
|
+
console.log(components.badge('VERSION', 'v1.3.6'));
|
|
482
482
|
console.log(components.badge('BUILD', 'passing'));
|
|
483
483
|
```
|
|
484
484
|
|
|
@@ -1065,6 +1065,44 @@ ansimax/
|
|
|
1065
1065
|
|
|
1066
1066
|
## 📝 Changelog
|
|
1067
1067
|
|
|
1068
|
+
### v1.3.6 — Mejoras de branch coverage
|
|
1069
|
+
|
|
1070
|
+
Release de mantenimiento. Cero cambios de comportamiento:
|
|
1071
|
+
|
|
1072
|
+
- 🧪 **+19 tests** cubriendo branches defensivos en panels, frames, loaders
|
|
1073
|
+
- 🧹 Mejorados comentarios `istanbul ignore` para branches genuinamente inalcanzables
|
|
1074
|
+
- ✅ Drop-in replacement para `1.3.5` — mismo `dist/` output
|
|
1075
|
+
|
|
1076
|
+
### v1.3.5 — Color science matemático + limpieza
|
|
1077
|
+
|
|
1078
|
+
Release patch enfocado en profundidad matemática y limpieza de código. Cero breaking changes:
|
|
1079
|
+
|
|
1080
|
+
- 🎨 **Espacio de color Oklab** — `rgbToOklab` / `oklabToRgb`. Gradientes perceptualmente uniformes
|
|
1081
|
+
- 🌈 **Espacio de color HSL** — `rgbToHsl` / `hslToRgb`. Rotación de matiz, manipulación de color
|
|
1082
|
+
- 🎯 **`lerpColor` / `gradientColor` / `gradientStops`** ahora aceptan `space: 'rgb' | 'hsl' | 'oklab'` (default `'rgb'`, retro-compatible)
|
|
1083
|
+
- 🥄 **`mixColors(a, b, t, space)`** — alias semántico, acepta hex strings o RGB
|
|
1084
|
+
- 📐 **`quantizeColor(color, levels)`** — reducción de paleta (efecto posterize)
|
|
1085
|
+
- ⚡ **Librería `easings`** — set completo de Robert Penner (quad/cubic/quart/quint/sine/expo/circ/back/elastic/bounce en in/out/inOut)
|
|
1086
|
+
- 🧮 **`isFiniteNumber` + `safeInt` + `clampByte`** — helpers numéricos exportados (consolida 25+ patrones defensivos duplicados)
|
|
1087
|
+
- 🧪 **+82 tests** incluyendo validación de correctitud matemática
|
|
1088
|
+
|
|
1089
|
+
```js
|
|
1090
|
+
import { lerpColor, easings, animate, mixColors } from 'ansimax';
|
|
1091
|
+
|
|
1092
|
+
// Midpoint de gradiente perceptualmente uniforme
|
|
1093
|
+
mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
|
|
1094
|
+
// → { r: 140, g: 83, b: 162 } — magenta vibrante
|
|
1095
|
+
// (vs RGB naive: { r: 128, g: 0, b: 128 } — púrpura turbio)
|
|
1096
|
+
|
|
1097
|
+
// Contador con animación bouncing
|
|
1098
|
+
await animate.countUp(0, 1000, {
|
|
1099
|
+
duration: 2000,
|
|
1100
|
+
easing: easings.easeOutBounce,
|
|
1101
|
+
});
|
|
1102
|
+
```
|
|
1103
|
+
|
|
1104
|
+
Drop-in replacement para `1.3.4`.
|
|
1105
|
+
|
|
1068
1106
|
### v1.3.4 — Features para animations, configure, utils
|
|
1069
1107
|
|
|
1070
1108
|
Release patch con features opt-in en varios módulos. Cero breaking changes:
|
package/README.md
CHANGED
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
_Colors • Gradients • Animations • ASCII Art • Pixel Art • Trees • Components • Themes_
|
|
8
8
|
|
|
9
9
|
[](LICENSE)
|
|
10
|
-
[](https://www.npmjs.com/package/ansimax)
|
|
11
11
|
[](tsconfig.json)
|
|
12
12
|
[](#testing)
|
|
13
13
|
[](#testing)
|
|
@@ -478,7 +478,7 @@ console.log(components.table([
|
|
|
478
478
|
['loaders', color.green('● ready'), '100%'],
|
|
479
479
|
], { borderStyle: 'rounded' }));
|
|
480
480
|
|
|
481
|
-
console.log(components.badge('VERSION', 'v1.3.
|
|
481
|
+
console.log(components.badge('VERSION', 'v1.3.6'));
|
|
482
482
|
console.log(components.badge('BUILD', 'passing'));
|
|
483
483
|
```
|
|
484
484
|
|
|
@@ -1065,6 +1065,44 @@ ansimax/
|
|
|
1065
1065
|
|
|
1066
1066
|
## 📝 Changelog
|
|
1067
1067
|
|
|
1068
|
+
### v1.3.6 — Branch coverage improvements
|
|
1069
|
+
|
|
1070
|
+
Maintenance release. Zero behavior changes:
|
|
1071
|
+
|
|
1072
|
+
- 🧪 **+19 tests** covering defensive branches in panels, frames, loaders
|
|
1073
|
+
- 🧹 Improved `istanbul ignore` comments for genuinely unreachable branches
|
|
1074
|
+
- ✅ Drop-in replacement for `1.3.5` — same `dist/` output
|
|
1075
|
+
|
|
1076
|
+
### v1.3.5 — Mathematical color science + cleanup
|
|
1077
|
+
|
|
1078
|
+
Patch release focused on math depth and code cleanliness. Zero breaking changes:
|
|
1079
|
+
|
|
1080
|
+
- 🎨 **Oklab color space** — `rgbToOklab` / `oklabToRgb`. Perceptually uniform gradients
|
|
1081
|
+
- 🌈 **HSL color space** — `rgbToHsl` / `hslToRgb`. Hue rotation, color manipulation
|
|
1082
|
+
- 🎯 **`lerpColor` / `gradientColor` / `gradientStops`** all accept `space: 'rgb' | 'hsl' | 'oklab'` (default `'rgb'`, retro-compatible)
|
|
1083
|
+
- 🥄 **`mixColors(a, b, t, space)`** — semantic alias, accepts hex strings or RGB
|
|
1084
|
+
- 📐 **`quantizeColor(color, levels)`** — palette reduction (posterize effect)
|
|
1085
|
+
- ⚡ **`easings` library** — full Robert Penner set (quad/cubic/quart/quint/sine/expo/circ/back/elastic/bounce in/out/inOut)
|
|
1086
|
+
- 🧮 **`isFiniteNumber` + `safeInt` + `clampByte`** — exported numeric helpers (consolidates 25+ duplicate defensive patterns)
|
|
1087
|
+
- 🧪 **+82 tests** including math correctness validation
|
|
1088
|
+
|
|
1089
|
+
```js
|
|
1090
|
+
import { lerpColor, easings, animate, mixColors } from 'ansimax';
|
|
1091
|
+
|
|
1092
|
+
// Perceptually-uniform gradient midpoint
|
|
1093
|
+
mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
|
|
1094
|
+
// → { r: 140, g: 83, b: 162 } — vibrant magenta
|
|
1095
|
+
// (vs naive RGB: { r: 128, g: 0, b: 128 } — muddy purple)
|
|
1096
|
+
|
|
1097
|
+
// Bouncing counter animation
|
|
1098
|
+
await animate.countUp(0, 1000, {
|
|
1099
|
+
duration: 2000,
|
|
1100
|
+
easing: easings.easeOutBounce,
|
|
1101
|
+
});
|
|
1102
|
+
```
|
|
1103
|
+
|
|
1104
|
+
Drop-in replacement for `1.3.4`.
|
|
1105
|
+
|
|
1068
1106
|
### v1.3.4 — Feature additions across animations, configure, utils
|
|
1069
1107
|
|
|
1070
1108
|
Patch release with opt-in additions to several modules. Zero breaking changes:
|
package/dist/index.d.mts
CHANGED
|
@@ -131,8 +131,43 @@ interface RGB {
|
|
|
131
131
|
g: number;
|
|
132
132
|
b: number;
|
|
133
133
|
}
|
|
134
|
+
/**
|
|
135
|
+
* Type guard: true when `n` is a finite number (rejects NaN, ±Infinity,
|
|
136
|
+
* non-numbers). Useful for input validation.
|
|
137
|
+
*
|
|
138
|
+
* @since 1.3.5
|
|
139
|
+
*/
|
|
140
|
+
declare const isFiniteNumber: (n: unknown) => n is number;
|
|
141
|
+
/**
|
|
142
|
+
* Coerce any value to a safe integer. Handles non-numbers, NaN, Infinity,
|
|
143
|
+
* and floats. Consolidates the `Math.max(0, Math.floor(Number(x) || 0))`
|
|
144
|
+
* pattern that appears across the codebase.
|
|
145
|
+
*
|
|
146
|
+
* @param value - Any value (will be coerced via `Number()`).
|
|
147
|
+
* @param fallback - Returned when `value` is non-finite. Default `0`.
|
|
148
|
+
* @param min - Lower bound (inclusive). Default `-Infinity`.
|
|
149
|
+
* @param max - Upper bound (inclusive). Default `Infinity`.
|
|
150
|
+
*
|
|
151
|
+
* @example
|
|
152
|
+
* ```ts
|
|
153
|
+
* safeInt('abc') // → 0
|
|
154
|
+
* safeInt(3.7) // → 3
|
|
155
|
+
* safeInt(-5, 0, 0, 100) // → 0 (clamped to min)
|
|
156
|
+
* safeInt(NaN, 50) // → 50 (fallback)
|
|
157
|
+
* safeInt(null, 1) // → 1 (fallback — null is not a real number)
|
|
158
|
+
* ```
|
|
159
|
+
*
|
|
160
|
+
* @since 1.3.5
|
|
161
|
+
*/
|
|
162
|
+
declare const safeInt: (value: unknown, fallback?: number, min?: number, max?: number) => number;
|
|
134
163
|
declare const clamp: (n: number, min: number, max: number) => number;
|
|
135
164
|
declare const lerp: (a: number, b: number, t: number) => number;
|
|
165
|
+
/**
|
|
166
|
+
* Clamp + round a number to the 0–255 byte range. Exported as of v1.3.5.
|
|
167
|
+
*
|
|
168
|
+
* @since 1.3.5
|
|
169
|
+
*/
|
|
170
|
+
declare const clampByte: (v: number) => number;
|
|
136
171
|
/** Returns true when a string is a valid 3- or 6-digit hex color. */
|
|
137
172
|
declare const isHexColor: (hex: string) => boolean;
|
|
138
173
|
/**
|
|
@@ -142,8 +177,112 @@ declare const isHexColor: (hex: string) => boolean;
|
|
|
142
177
|
declare const hexToRgb: (hex: string) => RGB;
|
|
143
178
|
/** Converts R, G, B values to a hex string. Values are clamped to 0–255. */
|
|
144
179
|
declare const rgbToHex: (r: number, g: number, b: number) => string;
|
|
145
|
-
|
|
146
|
-
|
|
180
|
+
interface HSL {
|
|
181
|
+
/** Hue in degrees, 0–360 (wraps; 360 ≡ 0). */
|
|
182
|
+
h: number;
|
|
183
|
+
/** Saturation in [0, 1] (0 = grayscale, 1 = pure color). */
|
|
184
|
+
s: number;
|
|
185
|
+
/** Lightness in [0, 1] (0 = black, 0.5 = pure, 1 = white). */
|
|
186
|
+
l: number;
|
|
187
|
+
}
|
|
188
|
+
/**
|
|
189
|
+
* Convert RGB (0–255) to HSL.
|
|
190
|
+
*
|
|
191
|
+
* @example
|
|
192
|
+
* rgbToHsl({ r: 255, g: 0, b: 0 }) // → { h: 0, s: 1, l: 0.5 }
|
|
193
|
+
* rgbToHsl({ r: 0, g: 255, b: 0 }) // → { h: 120, s: 1, l: 0.5 }
|
|
194
|
+
*
|
|
195
|
+
* @since 1.3.5
|
|
196
|
+
*/
|
|
197
|
+
declare const rgbToHsl: (rgb: RGB) => HSL;
|
|
198
|
+
/**
|
|
199
|
+
* Convert HSL to RGB (0–255). Hue wraps modulo 360.
|
|
200
|
+
*
|
|
201
|
+
* @example
|
|
202
|
+
* hslToRgb({ h: 0, s: 1, l: 0.5 }) // → { r: 255, g: 0, b: 0 }
|
|
203
|
+
* hslToRgb({ h: 240, s: 1, l: 0.5 }) // → { r: 0, g: 0, b: 255 }
|
|
204
|
+
*
|
|
205
|
+
* @since 1.3.5
|
|
206
|
+
*/
|
|
207
|
+
declare const hslToRgb: (hsl: HSL) => RGB;
|
|
208
|
+
interface Oklab {
|
|
209
|
+
/** Perceptual lightness in [0, 1]. */
|
|
210
|
+
L: number;
|
|
211
|
+
/** Green↔Red axis, roughly [-0.4, 0.4]. */
|
|
212
|
+
a: number;
|
|
213
|
+
/** Blue↔Yellow axis, roughly [-0.4, 0.4]. */
|
|
214
|
+
b: number;
|
|
215
|
+
}
|
|
216
|
+
/**
|
|
217
|
+
* Convert RGB (0–255) to Oklab. Perceptually uniform — interpolating in
|
|
218
|
+
* this space produces smoother gradients than naive RGB.
|
|
219
|
+
*
|
|
220
|
+
* @since 1.3.5
|
|
221
|
+
*/
|
|
222
|
+
declare const rgbToOklab: (rgb: RGB) => Oklab;
|
|
223
|
+
/**
|
|
224
|
+
* Convert Oklab back to RGB (0–255). Out-of-gamut values are clamped.
|
|
225
|
+
*
|
|
226
|
+
* @since 1.3.5
|
|
227
|
+
*/
|
|
228
|
+
declare const oklabToRgb: (oklab: Oklab) => RGB;
|
|
229
|
+
/** Color space to interpolate in. Default `'rgb'` for backward compatibility. */
|
|
230
|
+
type ColorSpace = 'rgb' | 'hsl' | 'oklab';
|
|
231
|
+
/**
|
|
232
|
+
* Linearly interpolate between two RGB colors. `t` is clamped to [0, 1].
|
|
233
|
+
*
|
|
234
|
+
* **v1.3.5+**: Accepts an optional 4th argument `space` to control which
|
|
235
|
+
* color space the interpolation happens in. `'oklab'` produces the
|
|
236
|
+
* smoothest, most perceptually uniform gradients but is ~3× slower than
|
|
237
|
+
* naive RGB. `'hsl'` is useful for hue rotation.
|
|
238
|
+
*
|
|
239
|
+
* @param a - Start color (RGB, 0–255).
|
|
240
|
+
* @param b - End color (RGB, 0–255).
|
|
241
|
+
* @param t - Mixing factor in [0, 1] (clamped).
|
|
242
|
+
* @param space - Interpolation space. Default `'rgb'` (backward-compat).
|
|
243
|
+
*
|
|
244
|
+
* @example
|
|
245
|
+
* ```ts
|
|
246
|
+
* lerpColor(red, blue, 0.5); // naive RGB midpoint
|
|
247
|
+
* lerpColor(red, blue, 0.5, 'oklab'); // perceptual midpoint
|
|
248
|
+
* lerpColor(red, blue, 0.5, 'hsl'); // through purple via hue
|
|
249
|
+
* ```
|
|
250
|
+
*/
|
|
251
|
+
declare const lerpColor: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
|
|
252
|
+
/**
|
|
253
|
+
* Semantic alias for `lerpColor`. Reads more naturally for the "blend
|
|
254
|
+
* two colors" use case, especially with a named color space.
|
|
255
|
+
*
|
|
256
|
+
* @example
|
|
257
|
+
* ```ts
|
|
258
|
+
* mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
|
|
259
|
+
* // Accepts hex strings OR RGB objects
|
|
260
|
+
* ```
|
|
261
|
+
*
|
|
262
|
+
* @since 1.3.5
|
|
263
|
+
*/
|
|
264
|
+
declare const mixColors: (a: RGB | string, b: RGB | string, t: number, space?: ColorSpace) => RGB;
|
|
265
|
+
/**
|
|
266
|
+
* Quantize a color to N levels per channel. Useful for palette
|
|
267
|
+
* reduction, posterization effects, or matching a constrained color
|
|
268
|
+
* palette (e.g., 16-color terminals).
|
|
269
|
+
*
|
|
270
|
+
* Mathematically: maps each channel to the nearest of `levels` evenly
|
|
271
|
+
* spaced values in [0, 255]. With `levels=2` you get pure on/off per
|
|
272
|
+
* channel (8 colors total). With `levels=4` you get a 64-color palette.
|
|
273
|
+
*
|
|
274
|
+
* @param color - Input RGB (0–255).
|
|
275
|
+
* @param levels - Number of discrete levels per channel (≥2, default `4`).
|
|
276
|
+
*
|
|
277
|
+
* @example
|
|
278
|
+
* ```ts
|
|
279
|
+
* quantizeColor({ r: 100, g: 150, b: 200 }, 4);
|
|
280
|
+
* // → snaps each channel to nearest of [0, 85, 170, 255]
|
|
281
|
+
* ```
|
|
282
|
+
*
|
|
283
|
+
* @since 1.3.5
|
|
284
|
+
*/
|
|
285
|
+
declare const quantizeColor: (color: RGB, levels?: number) => RGB;
|
|
147
286
|
/**
|
|
148
287
|
* Multi-stop gradient interpolation. Given a list of color stops and t in [0, 1],
|
|
149
288
|
* returns the interpolated RGB. Equivalent to a CSS `linear-gradient` sampler.
|
|
@@ -157,7 +296,7 @@ declare const lerpColor: (a: RGB, b: RGB, t: number) => RGB;
|
|
|
157
296
|
* gradientColor([red, blue], -1) → red (t clamped to 0)
|
|
158
297
|
* gradientColor([red, blue], 99) → blue (t clamped to 1)
|
|
159
298
|
*/
|
|
160
|
-
declare const gradientColor: (colors: RGB[], t: number) => RGB;
|
|
299
|
+
declare const gradientColor: (colors: RGB[], t: number, space?: ColorSpace) => RGB;
|
|
161
300
|
declare const rgbTo256: (r: number, g: number, b: number) => number;
|
|
162
301
|
declare const stripAnsi$2: (str: string) => string;
|
|
163
302
|
/**
|
|
@@ -365,17 +504,23 @@ declare const padBoth: (str: string, width: number, ch?: string) => string;
|
|
|
365
504
|
* @param start - Start hex color (e.g. `'#ff0000'`).
|
|
366
505
|
* @param end - End hex color (e.g. `'#0000ff'`).
|
|
367
506
|
* @param count - Number of stops (>= 2; clamped if smaller).
|
|
507
|
+
* @param space - **v1.3.5+** Color space for interpolation:
|
|
508
|
+
* `'rgb'` (default, fast), `'hsl'` (hue rotation),
|
|
509
|
+
* or `'oklab'` (perceptually uniform).
|
|
368
510
|
* @returns Array of hex strings, including both endpoints.
|
|
369
511
|
*
|
|
370
512
|
* @example
|
|
371
513
|
* ```ts
|
|
372
514
|
* import { gradientStops } from 'ansimax';
|
|
373
515
|
*
|
|
516
|
+
* // Naive RGB (default)
|
|
374
517
|
* const stops = gradientStops('#ff0000', '#0000ff', 5);
|
|
375
|
-
*
|
|
518
|
+
*
|
|
519
|
+
* // Perceptually uniform (smoother visual transition)
|
|
520
|
+
* const smooth = gradientStops('#ff0000', '#0000ff', 5, 'oklab');
|
|
376
521
|
* ```
|
|
377
522
|
*/
|
|
378
|
-
declare const gradientStops: (start: string, end: string, count: number) => string[];
|
|
523
|
+
declare const gradientStops: (start: string, end: string, count: number, space?: ColorSpace) => string[];
|
|
379
524
|
/**
|
|
380
525
|
* Escape a string for safe use inside a regular expression literal.
|
|
381
526
|
* Escapes all 12 regex meta-characters: `. * + ? ^ $ { } ( ) | [ ] \`.
|
|
@@ -1376,7 +1521,7 @@ declare const images: {
|
|
|
1376
1521
|
createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
|
|
1377
1522
|
colors: {
|
|
1378
1523
|
hex: (h: unknown) => RGB | null;
|
|
1379
|
-
lerp: (a: RGB, b: RGB, t: number) => RGB;
|
|
1524
|
+
lerp: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
|
|
1380
1525
|
blend: (fg: Pixel, bg: RGB) => RGB;
|
|
1381
1526
|
};
|
|
1382
1527
|
clearAnsiCache: () => void;
|
|
@@ -2706,6 +2851,41 @@ declare const json: {
|
|
|
2706
2851
|
pretty: (value: unknown, opts?: PrettyOptions) => string;
|
|
2707
2852
|
};
|
|
2708
2853
|
|
|
2854
|
+
type EasingFunction = (t: number) => number;
|
|
2855
|
+
/**
|
|
2856
|
+
* Union of all built-in easing names in the comprehensive Robert Penner
|
|
2857
|
+
* library. Provides autocompletion and prevents typos when looking up
|
|
2858
|
+
* functions in `easings`.
|
|
2859
|
+
*
|
|
2860
|
+
* **Note**: This is the v1.3.5 extended library. The original `EasingName`
|
|
2861
|
+
* from the gradient module is a smaller union (5 values) and is
|
|
2862
|
+
* preserved for backward compatibility.
|
|
2863
|
+
*
|
|
2864
|
+
* @since 1.3.5
|
|
2865
|
+
*/
|
|
2866
|
+
type EasingLibraryName = 'linear' | 'easeInQuad' | 'easeOutQuad' | 'easeInOutQuad' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuart' | 'easeOutQuart' | 'easeInOutQuart' | 'easeInQuint' | 'easeOutQuint' | 'easeInOutQuint' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInExpo' | 'easeOutExpo' | 'easeInOutExpo' | 'easeInCirc' | 'easeOutCirc' | 'easeInOutCirc' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack' | 'easeInElastic' | 'easeOutElastic' | 'easeInOutElastic' | 'easeInBounce' | 'easeOutBounce' | 'easeInOutBounce';
|
|
2867
|
+
/**
|
|
2868
|
+
* A library of named easing functions. Each maps `t ∈ [0, 1]` to an
|
|
2869
|
+
* eased value, typically also in `[0, 1]` (back/elastic briefly
|
|
2870
|
+
* overshoot by design).
|
|
2871
|
+
*
|
|
2872
|
+
* Typed as `Record<EasingLibraryName, EasingFunction>` so all 31 keys are
|
|
2873
|
+
* known to TypeScript — autocompletion + no `possibly undefined` errors
|
|
2874
|
+
* when accessing standard names.
|
|
2875
|
+
*
|
|
2876
|
+
* @since 1.3.5
|
|
2877
|
+
*/
|
|
2878
|
+
declare const easings: Record<EasingLibraryName, EasingFunction>;
|
|
2879
|
+
/**
|
|
2880
|
+
* Resolve an easing reference to a function. Accepts a function (returned
|
|
2881
|
+
* as-is), a named string in `easings` (typed `EasingName` for autocomplete,
|
|
2882
|
+
* but any string is allowed at runtime with linear fallback), or
|
|
2883
|
+
* `undefined`/invalid input (returns `linear`).
|
|
2884
|
+
*
|
|
2885
|
+
* @since 1.3.5
|
|
2886
|
+
*/
|
|
2887
|
+
declare const resolveEasingByName: (e: EasingLibraryName | string | EasingFunction | undefined | null) => EasingFunction;
|
|
2888
|
+
|
|
2709
2889
|
declare const ansimax: {
|
|
2710
2890
|
color: {
|
|
2711
2891
|
black: ColorFn;
|
|
@@ -2866,7 +3046,7 @@ declare const ansimax: {
|
|
|
2866
3046
|
createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
|
|
2867
3047
|
colors: {
|
|
2868
3048
|
hex: (h: unknown) => RGB | null;
|
|
2869
|
-
lerp: (a: RGB, b: RGB, t: number) => RGB;
|
|
3049
|
+
lerp: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
|
|
2870
3050
|
blend: (fg: Pixel, bg: RGB) => RGB;
|
|
2871
3051
|
};
|
|
2872
3052
|
clearAnsiCache: () => void;
|
|
@@ -2874,4 +3054,4 @@ declare const ansimax: {
|
|
|
2874
3054
|
configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
|
|
2875
3055
|
};
|
|
2876
3056
|
|
|
2877
|
-
export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type GridOptions, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clearAnsiCache, clearColorCache, clearLine, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, escapeForRegex, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, gradientStops, graphemes, grid, hasFont, hexToRgb, hideCursor, hsplit, hyperlink, images, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureBlock, measureTree, memoize, nextTick, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rotate90, safeJson, screen, setConfigValue, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$2 as stripAnsi, stripAnsi$1 as stripAnsiCodes, stripAnsi as stripAnsiColors, subscribeConfig, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
|
|
3057
|
+
export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSpace, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingFunction, type EasingLibraryName, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type GridOptions, type HSL, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type Oklab, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clampByte, clearAnsiCache, clearColorCache, clearLine, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, easings, escapeForRegex, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, gradientStops, graphemes, grid, hasFont, hexToRgb, hideCursor, hslToRgb, hsplit, hyperlink, images, isFiniteNumber, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, measureBlock, measureTree, memoize, mixColors, nextTick, oklabToRgb, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, pauseListeners, presetNames, presets, quantizeColor, rainbow, registerFont, registerPreset, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resolveEasingByName, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rgbToHsl, rgbToOklab, rotate90, safeInt, safeJson, screen, setConfigValue, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$2 as stripAnsi, stripAnsi$1 as stripAnsiCodes, stripAnsi as stripAnsiColors, subscribeConfig, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
|