Color

Un sistema de color basado en clases, con ayudas de conversión para trabajar con RGB, RGBA, HSL, HSLA, HSB/HSV y colores hexadecimales. Trae una clase Color bien surtida, clases de valor inmutables (Rgb, Rgba, Hsl, Hsla), el generador de paletas ColorScheme, un juego de funciones de conversión sueltas y FMT, el mapa de estilos ANSI para la terminal.

Las ayudas más sencillas —hexToRgb, rgbToHex y randomColor— tienen página propia: hexToRgb, rgbToHex, randomColor. Se reexportan desde este mismo módulo.

API

Color

La clase principal de color. Acepta una cadena hexadecimal, un array [r, g, b, a] o los canales como números sueltos, y calcula de inmediato todas las representaciones (rgb, rgba, hex, hsl, hsla) además de los accesores directos a cada canal.

Constructor

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

Parámetros

Properties

Methods

Rgb

Un objeto de valor RGB construido a partir de un array. toString() devuelve una cadena CSS rgb(...).

Constructor

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

Propiedades y métodos

Rgba

Extiende Rgb con un canal alfa. toString() devuelve una cadena CSS rgba(...).

Constructor

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

Propiedades y métodos

Hsl

Un objeto de valor HSL construido a partir de un array. toString() devuelve una cadena CSS hsl(...).

Constructor

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

Propiedades y métodos

Hsla

Extiende Hsl con un canal alfa. toString() devuelve una cadena CSS hsla(...).

Constructor

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

Propiedades y métodos

ColorScheme

Genera una paleta de objetos Color emparentados, ya sea a partir de una lista de colores o de un color base girado según un array de ángulos de tono. Los métodos de fábrica estáticos cubren los esquemas de armonía más habituales.

Constructor

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

Propiedades y métodos

Métodos de fábrica estáticos

Cada uno recibe un color base y devuelve un ColorScheme con un juego de ángulos de tono ya fijado.

Funciones de conversión

Funciones sueltas que Color usa por dentro; todas se exportan para que las uses tal cual. Donde una función recibe tres canales, el primer argumento puede ser también un único array (por ejemplo rgbToHsl([r, g, b])).

componentToHex, rgbToHex y hexToRgb son las piezas de bajo nivel; véanse rgbToHex y hexToRgb.

Ayudas para el alfa

Aquí el alfa va de 0 a 100, la misma escala en porcentaje que el resto del módulo usa para la saturación y la luminosidad, y no el 0–1 que toma rgba() en CSS.

Ayudas de mezcla y matemática de shaders

La matemática de mezcla y de corrección de color que hay detrás de los filtros de posprocesado de ranuts/visual (ColorAdjustFilter y compañía), exportada aquí para reaprovecharla del lado de la CPU (calcular la vista previa de una miniatura, digamos, sin levantar una tubería de GPU). A diferencia del resto del módulo, aquí los canales van de 0 a 1, ni 0–255 ni 0–100, siguiendo la convención de los shaders.

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

// Mezcla en modo trama dos colores de 0 a 1
const screened = blendScreen([0.8, 0.2, 0.1], [0.1, 0.5, 0.9]);

// Sube el contraste y baja un poco el brillo
const graded = brightnessContrast([0.6, 0.6, 0.6], -0.05, 1.2);

// Toma una muestra de una paleta degradada procedural en 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]);

// La matemática con gamma correcta (mezclas, iluminación) debe hacerse en espacio lineal
const linear = srgbToLinear(0.5);
const backToSrgb = linearToSrgb(linear); // ≈ 0.5

Patrones de formato

Expresiones regulares para validar cadenas de color. RGB_REGEX y RGBA_REGEX no toleran espacios; quítalos antes (value.replace(/\s+/g, '')).

FMT

Un registro de pares de códigos de escape ANSI para dar estilo y color al texto de la terminal. Cada entrada es una tupla [abrir, cerrar] con la que envuelves una cadena para darle estilo en la salida.

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

Claves disponibles: bold, dim, reset, italic, underline, inverse, hidden, strikethrough, black, red, green, yellow, blue, magenta, cyan, white, gray, y las variantes de fondo bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite.

Ejemplo

Crear un Color

import { Color } from 'ranuts';

// A partir de una cadena hexadecimal (forma corta o larga, con o sin #)
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%)'

// A partir de los canales
const green = new Color(0, 255, 0);
console.log(green.hex); // '#00ff00'

// A partir de un array (con alfa)
const blue = new Color([0, 0, 255, 0.5]);
console.log(blue.rgba.toString()); // 'rgba(0,0,255,0.5)'

Cambiar un Color a través de HSL

import { Color } from 'ranuts';

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

color.setHue(120); // gira el tono hasta el verde
console.log(color.rgb.toString()); // 'rgb(0,255,0)'

color.setLum(25); // más oscuro
color.setSat(50); // baja la saturación
color.setAlpha(0.4);
console.log(color.rgba.toString()); // 'rgba(...,0.4)'

Armar una paleta con ColorScheme

import { ColorScheme } from 'ranuts';

// Pareja complementaria a partir de un color base
const compl = ColorScheme.Compl('#3498db');
console.log(compl.palette.map((c) => c.hex));

// Esquema triádico (el base y dos colores separados 120°)
const triad = ColorScheme.Triad('#3498db');
console.log(triad.palette.length); // 3

// Directamente a partir de una lista de colores
const custom = new ColorScheme(['#ff0000', '#00ff00', '#0000ff']);
console.log(custom.palette.map((c) => c.hsl.toString()));

Usar las funciones de conversión

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'

// Donde está documentado, también se acepta un array como entrada
console.log(rgbToHsl([0, 128, 255])); // [h, s, l]

Dar estilo a la salida de la terminal con FMT

import { FMT } from 'ranuts';

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

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

Notas

1. Todo se calcula de entrada: un Color calcula todas sus representaciones en el constructor, así que hex, rgb, rgba, hsl y hsla están de acuerdo desde el momento en que se crea.
2. Los setters de HSL recalculan el RGB: setHue, setSat y setLum actualizan el HSL y luego vuelven a derivar el RGB y el hexadecimal con updateFromHsl. setAlpha solo toca rgba y hsla.
3. Entrada por array o por canales: varias funciones de conversión (rgbToHex, rgbToHsl, hslToRgb) aceptan tanto tres canales sueltos como un único array en el primer argumento.
4. HSV frente a HSB: hsvToRgb es otro nombre de hsbToRgb, y hsvToHsl otro nombre de la conversión de HSB a HSL. Aquí HSV y HSB se refieren al mismo modelo.
5. FMT solo sirve en la terminal: las secuencias de escape ANSI se ven como estilo únicamente en una terminal que las admita; en la consola del navegador aparecen como caracteres de control en crudo.