Color

A class-based color system with conversion helpers for working with RGB, RGBA, HSL, HSLA, HSB/HSV and hexadecimal colors. It provides a rich Color class, immutable value classes (Rgb, Rgba, Hsl, Hsla), a ColorScheme palette generator, a set of standalone conversion functions, and the FMT terminal ANSI style map.

The simpler helpers hexToRgb, rgbToHex and randomColor are documented on their own pages: hexToRgb, rgbToHex, randomColor. They are re-exported from the same module.

API

Color

The main color class. It accepts a hex string, an [r, g, b, a] array, or separate channel numbers, and eagerly computes every representation (rgb, rgba, hex, hsl, hsla) plus flat channel accessors.

Constructor

new Color(
  r: string | number | Array<string | number>,
  g?: string | number,
  b?: string | number,
  a?: string | number,
)

Parameters

Properties

Methods

Rgb

An RGB value object built from an array. toString() returns a CSS rgb(...) string.

Constructor

new Rgb(col: Array<string | number>) // [r, g, b]

Properties & Methods

Rgba

Extends Rgb with an alpha channel. toString() returns a CSS rgba(...) string.

Constructor

new Rgba(col: Array<string | number>) // [r, g, b, a]

Properties & Methods

Hsl

An HSL value object built from an array. toString() returns a CSS hsl(...) string.

Constructor

new Hsl(col: Array<string | number>) // [h, s, l]

Properties & Methods

Hsla

Extends Hsl with an alpha channel. toString() returns a CSS hsla(...) string.

Constructor

new Hsla(col: Array<string | number>) // [h, s, l, a]

Properties & Methods

ColorScheme

Generates a palette of related Color objects, either directly from a list of colors or from a base color rotated by an array of hue angles. Static factory methods cover common color-harmony schemes.

Constructor

new ColorScheme(colorVal: (string | number)[], angleArray: number[])

Properties & Methods

Static factory methods

Each takes a base color value and returns a ColorScheme with a preset hue-angle set.

Conversion functions

Standalone functions used internally by Color; each is exported for direct use. Where a function accepts three channel arguments, the first may also be a single array (e.g. rgbToHsl([r, g, b])).

componentToHex, rgbToHex and hexToRgb are the low-level building blocks; see rgbToHex and hexToRgb.

Alpha helpers

Alpha is expressed as 0–100, matching the percentage scale the rest of this module uses for saturation and lightness, not the 0–1 that CSS rgba() takes.

Blend & shader-math helpers

The colour-grade and blend math behind ranuts/visual's post-processing filters (ColorAdjustFilter and friends), exported here for CPU-side reuse (computing a thumbnail preview, say, without spinning up a GPU pipeline). Unlike the rest of this module, channels here are 0–1, not 0–255 or 0–100, matching the convention shaders use.

import { blendScreen, brightnessContrast, cosinePalette, srgbToLinear, linearToSrgb } from 'ranuts/utils';

// Screen-blend two 0-1 colors
const screened = blendScreen([0.8, 0.2, 0.1], [0.1, 0.5, 0.9]);

// Push contrast up and brightness down slightly
const graded = brightnessContrast([0.6, 0.6, 0.6], -0.05, 1.2);

// Sample a procedural gradient palette at t=0.35
const swatch = cosinePalette(0.35, [0.5, 0.5, 0.5], [0.5, 0.5, 0.5], [1, 1, 1], [0, 0.33, 0.67]);

// Gamma-correct math (blending, lighting) should happen in linear space
const linear = srgbToLinear(0.5);
const backToSrgb = linearToSrgb(linear); // ≈ 0.5

Format patterns

Regular expressions for validating colour strings. RGB_REGEX and RGBA_REGEX do not tolerate spaces; strip them first (value.replace(/\s+/g, '')).

FMT

A record of ANSI terminal escape-code pairs for text styling and coloring. Each entry is a [open, close] tuple you wrap around a string to style terminal output.

const FMT: Record<string, Array<string>>;

Available keys: bold, dim, reset, italic, underline, inverse, hidden, strikethrough, black, red, green, yellow, blue, magenta, cyan, white, gray, and the background variants bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite.

Example

Creating a Color

import { Color } from 'ranuts';

// From a hex string (short or long form, # optional)
const red = new Color('#ff0000');
console.log(red.hex); // '#ff0000'
console.log(red.rgb.toString()); // 'rgb(255,0,0)'
console.log(red.hsl.toString()); // 'hsl(0,100%,50%)'

// From channels
const green = new Color(0, 255, 0);
console.log(green.hex); // '#00ff00'

// From an array (with alpha)
const blue = new Color([0, 0, 255, 0.5]);
console.log(blue.rgba.toString()); // 'rgba(0,0,255,0.5)'

Mutating a Color via HSL

import { Color } from 'ranuts';

const color = new Color('#ff0000');

color.setHue(120); // rotate hue to green
console.log(color.rgb.toString()); // 'rgb(0,255,0)'

color.setLum(25); // darker
color.setSat(50); // desaturate
color.setAlpha(0.4);
console.log(color.rgba.toString()); // 'rgba(...,0.4)'

Building a palette with ColorScheme

import { ColorScheme } from 'ranuts';

// Complementary pair from a base color
const compl = ColorScheme.Compl('#3498db');
console.log(compl.palette.map((c) => c.hex));

// Triadic scheme (base + two colors 120° apart)
const triad = ColorScheme.Triad('#3498db');
console.log(triad.palette.length); // 3

// Directly from a list of colors
const custom = new ColorScheme(['#ff0000', '#00ff00', '#0000ff']);
console.log(custom.palette.map((c) => c.hsl.toString()));

Using the conversion functions

import { rgbToHsl, hslToRgb, rgbToHsb, hsbToRgb, componentToHex } from 'ranuts';

console.log(rgbToHsl(255, 0, 0)); // [0, 100, 50]
console.log(hslToRgb(0, 100, 50)); // [255, 0, 0]
console.log(rgbToHsb(255, 0, 0)); // [0, 100, 100]
console.log(hsbToRgb(0, 100, 100)); // [255, 0, 0]
console.log(componentToHex(255)); // 'ff'

// Array input is also accepted where documented
console.log(rgbToHsl([0, 128, 255])); // [h, s, l]

Styling terminal output with FMT

import { FMT } from 'ranuts';

const [open, close] = FMT.green;
console.log(`${open}success${close}`); // green "success" in a terminal

const bold = FMT.bold;
console.log(`${bold[0]}important${bold[1]}`);

Notes

1. Eager computation: A Color computes all representations in its constructor, so hex, rgb, rgba, hsl and hsla are always in sync at construction time.
2. HSL setters recompute RGB: setHue / setSat / setLum update HSL and then re-derive RGB and hex via updateFromHsl. setAlpha only affects rgba and hsla.
3. Array-or-channels inputs: Several conversion functions (rgbToHex, rgbToHsl, hslToRgb) accept either three channel arguments or a single array as the first argument.
4. HSV vs HSB: hsvToRgb is an alias of hsbToRgb, and hsvToHsl an alias of the HSB→HSL conversion. HSV and HSB refer to the same model here.
5. FMT is terminal-only: The ANSI escape sequences render as styling only in a terminal that supports them; in a browser console they appear as raw control characters.