ansimax 1.3.4 → 1.3.5

package/dist/index.d.ts

@@ -131,8 +131,43 @@ interface RGB {
     g: number;
     b: number;
 }
+/**
+ * Type guard: true when `n` is a finite number (rejects NaN, ±Infinity,
+ * non-numbers). Useful for input validation.
+ *
+ * @since 1.3.5
+ */
+declare const isFiniteNumber: (n: unknown) => n is number;
+/**
+ * Coerce any value to a safe integer. Handles non-numbers, NaN, Infinity,
+ * and floats. Consolidates the `Math.max(0, Math.floor(Number(x) || 0))`
+ * pattern that appears across the codebase.
+ *
+ * @param value    - Any value (will be coerced via `Number()`).
+ * @param fallback - Returned when `value` is non-finite. Default `0`.
+ * @param min      - Lower bound (inclusive). Default `-Infinity`.
+ * @param max      - Upper bound (inclusive). Default `Infinity`.
+ *
+ * @example
+ * ```ts
+ * safeInt('abc')                  // → 0
+ * safeInt(3.7)                    // → 3
+ * safeInt(-5, 0, 0, 100)          // → 0  (clamped to min)
+ * safeInt(NaN, 50)                // → 50 (fallback)
+ * safeInt(null, 1)                // → 1  (fallback — null is not a real number)
+ * ```
+ *
+ * @since 1.3.5
+ */
+declare const safeInt: (value: unknown, fallback?: number, min?: number, max?: number) => number;
 declare const clamp: (n: number, min: number, max: number) => number;
 declare const lerp: (a: number, b: number, t: number) => number;
+/**
+ * Clamp + round a number to the 0–255 byte range. Exported as of v1.3.5.
+ *
+ * @since 1.3.5
+ */
+declare const clampByte: (v: number) => number;
 /** Returns true when a string is a valid 3- or 6-digit hex color. */
 declare const isHexColor: (hex: string) => boolean;
 /**
@@ -142,8 +177,112 @@ declare const isHexColor: (hex: string) => boolean;
 declare const hexToRgb: (hex: string) => RGB;
 /** Converts R, G, B values to a hex string. Values are clamped to 0–255. */
 declare const rgbToHex: (r: number, g: number, b: number) => string;
-/** Linearly interpolates between two RGB colors. t is clamped to [0, 1]. */
-declare const lerpColor: (a: RGB, b: RGB, t: number) => RGB;
+interface HSL {
+    /** Hue in degrees, 0–360 (wraps; 360 ≡ 0). */
+    h: number;
+    /** Saturation in [0, 1] (0 = grayscale, 1 = pure color). */
+    s: number;
+    /** Lightness in [0, 1] (0 = black, 0.5 = pure, 1 = white). */
+    l: number;
+}
+/**
+ * Convert RGB (0–255) to HSL.
+ *
+ * @example
+ * rgbToHsl({ r: 255, g: 0, b: 0 })  // → { h: 0,   s: 1, l: 0.5 }
+ * rgbToHsl({ r: 0, g: 255, b: 0 })  // → { h: 120, s: 1, l: 0.5 }
+ *
+ * @since 1.3.5
+ */
+declare const rgbToHsl: (rgb: RGB) => HSL;
+/**
+ * Convert HSL to RGB (0–255). Hue wraps modulo 360.
+ *
+ * @example
+ * hslToRgb({ h: 0,   s: 1, l: 0.5 })  // → { r: 255, g: 0,   b: 0   }
+ * hslToRgb({ h: 240, s: 1, l: 0.5 })  // → { r: 0,   g: 0,   b: 255 }
+ *
+ * @since 1.3.5
+ */
+declare const hslToRgb: (hsl: HSL) => RGB;
+interface Oklab {
+    /** Perceptual lightness in [0, 1]. */
+    L: number;
+    /** Green↔Red axis, roughly [-0.4, 0.4]. */
+    a: number;
+    /** Blue↔Yellow axis, roughly [-0.4, 0.4]. */
+    b: number;
+}
+/**
+ * Convert RGB (0–255) to Oklab. Perceptually uniform — interpolating in
+ * this space produces smoother gradients than naive RGB.
+ *
+ * @since 1.3.5
+ */
+declare const rgbToOklab: (rgb: RGB) => Oklab;
+/**
+ * Convert Oklab back to RGB (0–255). Out-of-gamut values are clamped.
+ *
+ * @since 1.3.5
+ */
+declare const oklabToRgb: (oklab: Oklab) => RGB;
+/** Color space to interpolate in. Default `'rgb'` for backward compatibility. */
+type ColorSpace = 'rgb' | 'hsl' | 'oklab';
+/**
+ * Linearly interpolate between two RGB colors. `t` is clamped to [0, 1].
+ *
+ * **v1.3.5+**: Accepts an optional 4th argument `space` to control which
+ * color space the interpolation happens in. `'oklab'` produces the
+ * smoothest, most perceptually uniform gradients but is ~3× slower than
+ * naive RGB. `'hsl'` is useful for hue rotation.
+ *
+ * @param a     - Start color (RGB, 0–255).
+ * @param b     - End color (RGB, 0–255).
+ * @param t     - Mixing factor in [0, 1] (clamped).
+ * @param space - Interpolation space. Default `'rgb'` (backward-compat).
+ *
+ * @example
+ * ```ts
+ * lerpColor(red, blue, 0.5);                   // naive RGB midpoint
+ * lerpColor(red, blue, 0.5, 'oklab');          // perceptual midpoint
+ * lerpColor(red, blue, 0.5, 'hsl');            // through purple via hue
+ * ```
+ */
+declare const lerpColor: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
+/**
+ * Semantic alias for `lerpColor`. Reads more naturally for the "blend
+ * two colors" use case, especially with a named color space.
+ *
+ * @example
+ * ```ts
+ * mixColors('#ff0000', '#0000ff', 0.5, 'oklab');
+ * // Accepts hex strings OR RGB objects
+ * ```
+ *
+ * @since 1.3.5
+ */
+declare const mixColors: (a: RGB | string, b: RGB | string, t: number, space?: ColorSpace) => RGB;
+/**
+ * Quantize a color to N levels per channel. Useful for palette
+ * reduction, posterization effects, or matching a constrained color
+ * palette (e.g., 16-color terminals).
+ *
+ * Mathematically: maps each channel to the nearest of `levels` evenly
+ * spaced values in [0, 255]. With `levels=2` you get pure on/off per
+ * channel (8 colors total). With `levels=4` you get a 64-color palette.
+ *
+ * @param color  - Input RGB (0–255).
+ * @param levels - Number of discrete levels per channel (≥2, default `4`).
+ *
+ * @example
+ * ```ts
+ * quantizeColor({ r: 100, g: 150, b: 200 }, 4);
+ * // → snaps each channel to nearest of [0, 85, 170, 255]
+ * ```
+ *
+ * @since 1.3.5
+ */
+declare const quantizeColor: (color: RGB, levels?: number) => RGB;
 /**
  * Multi-stop gradient interpolation. Given a list of color stops and t in [0, 1],
  * 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;
  * gradientColor([red, blue], -1)  → red (t clamped to 0)
  * gradientColor([red, blue], 99)  → blue (t clamped to 1)
  */
-declare const gradientColor: (colors: RGB[], t: number) => RGB;
+declare const gradientColor: (colors: RGB[], t: number, space?: ColorSpace) => RGB;
 declare const rgbTo256: (r: number, g: number, b: number) => number;
 declare const stripAnsi$2: (str: string) => string;
 /**
@@ -365,17 +504,23 @@ declare const padBoth: (str: string, width: number, ch?: string) => string;
  * @param start - Start hex color (e.g. `'#ff0000'`).
  * @param end   - End hex color (e.g. `'#0000ff'`).
  * @param count - Number of stops (>= 2; clamped if smaller).
+ * @param space - **v1.3.5+** Color space for interpolation:
+ *                `'rgb'` (default, fast), `'hsl'` (hue rotation),
+ *                or `'oklab'` (perceptually uniform).
  * @returns Array of hex strings, including both endpoints.
  *
  * @example
  * ```ts
  * import { gradientStops } from 'ansimax';
  *
+ * // Naive RGB (default)
  * const stops = gradientStops('#ff0000', '#0000ff', 5);
- * // → ['#ff0000', '#bf003f', '#7f007f', '#3f00bf', '#0000ff']
+ *
+ * // Perceptually uniform (smoother visual transition)
+ * const smooth = gradientStops('#ff0000', '#0000ff', 5, 'oklab');
  * ```
  */
-declare const gradientStops: (start: string, end: string, count: number) => string[];
+declare const gradientStops: (start: string, end: string, count: number, space?: ColorSpace) => string[];
 /**
  * Escape a string for safe use inside a regular expression literal.
  * Escapes all 12 regex meta-characters: `. * + ? ^ $ { } ( ) | [ ] \`.
@@ -1376,7 +1521,7 @@ declare const images: {
     createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
     colors: {
         hex: (h: unknown) => RGB | null;
-        lerp: (a: RGB, b: RGB, t: number) => RGB;
+        lerp: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
         blend: (fg: Pixel, bg: RGB) => RGB;
     };
     clearAnsiCache: () => void;
@@ -2706,6 +2851,41 @@ declare const json: {
     pretty: (value: unknown, opts?: PrettyOptions) => string;
 };
 
+type EasingFunction = (t: number) => number;
+/**
+ * Union of all built-in easing names in the comprehensive Robert Penner
+ * library. Provides autocompletion and prevents typos when looking up
+ * functions in `easings`.
+ *
+ * **Note**: This is the v1.3.5 extended library. The original `EasingName`
+ * from the gradient module is a smaller union (5 values) and is
+ * preserved for backward compatibility.
+ *
+ * @since 1.3.5
+ */
+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';
+/**
+ * A library of named easing functions. Each maps `t ∈ [0, 1]` to an
+ * eased value, typically also in `[0, 1]` (back/elastic briefly
+ * overshoot by design).
+ *
+ * Typed as `Record<EasingLibraryName, EasingFunction>` so all 31 keys are
+ * known to TypeScript — autocompletion + no `possibly undefined` errors
+ * when accessing standard names.
+ *
+ * @since 1.3.5
+ */
+declare const easings: Record<EasingLibraryName, EasingFunction>;
+/**
+ * Resolve an easing reference to a function. Accepts a function (returned
+ * as-is), a named string in `easings` (typed `EasingName` for autocomplete,
+ * but any string is allowed at runtime with linear fallback), or
+ * `undefined`/invalid input (returns `linear`).
+ *
+ * @since 1.3.5
+ */
+declare const resolveEasingByName: (e: EasingLibraryName | string | EasingFunction | undefined | null) => EasingFunction;
+
 declare const ansimax: {
     color: {
         black: ColorFn;
@@ -2866,7 +3046,7 @@ declare const ansimax: {
         createCanvas: (width: number, height: number, fillColor?: Pixel) => Canvas;
         colors: {
             hex: (h: unknown) => RGB | null;
-            lerp: (a: RGB, b: RGB, t: number) => RGB;
+            lerp: (a: RGB, b: RGB, t: number, space?: ColorSpace) => RGB;
             blend: (fg: Pixel, bg: RGB) => RGB;
         };
         clearAnsiCache: () => void;
@@ -2874,4 +3054,4 @@ declare const ansimax: {
     configure: (opts?: AnsimaxConfig, meta?: ConfigureOptions) => void;
 };
 
-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 };
+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 };