Color

Um sistema de cor baseado em classes, com auxiliares de conversão para trabalhar com RGB, RGBA, HSL, HSLA, HSB/HSV e cores hexadecimais. Traz uma classe Color bem servida, classes de valor imutáveis (Rgb, Rgba, Hsl, Hsla), o gerador de paletas ColorScheme, um conjunto de funções de conversão avulsas e o FMT, o mapa de estilos ANSI para o terminal.

Os auxiliares mais simples — hexToRgb, rgbToHex e randomColor — têm página própria: hexToRgb, rgbToHex, randomColor. Todos são reexportados deste mesmo módulo.

API

Color

A classe principal de cor. Aceita uma string hexadecimal, um array [r, g, b, a] ou os canais como números separados, e já calcula de imediato todas as representações (rgb, rgba, hex, hsl, hsla), além dos acessores diretos a cada canal.

Construtor

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

Parâmetros

Properties

Methods

Rgb

Um objeto de valor RGB montado a partir de um array. O toString() devolve uma string CSS rgb(...).

Construtor

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

Propriedades e métodos

Rgba

Estende o Rgb com um canal alfa. O toString() devolve uma string CSS rgba(...).

Construtor

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

Propriedades e métodos

Hsl

Um objeto de valor HSL montado a partir de um array. O toString() devolve uma string CSS hsl(...).

Construtor

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

Propriedades e métodos

Hsla

Estende o Hsl com um canal alfa. O toString() devolve uma string CSS hsla(...).

Construtor

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

Propriedades e métodos

ColorScheme

Gera uma paleta de objetos Color aparentados, seja a partir de uma lista de cores, seja de uma cor base girada por um array de ângulos de matiz. Os métodos de fábrica estáticos cobrem os esquemas de harmonia mais comuns.

Construtor

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

Propriedades e métodos

Métodos de fábrica estáticos

Cada um recebe uma cor base e devolve um ColorScheme com um conjunto de ângulos de matiz já definido.

Funções de conversão

Funções avulsas que o Color usa por dentro; todas são exportadas para você usar direto. Onde uma função recebe três canais, o primeiro argumento pode ser também um único array (por exemplo rgbToHsl([r, g, b])).

componentToHex, rgbToHex e hexToRgb são as peças de baixo nível; veja rgbToHex e hexToRgb.

Auxiliares de alfa

Aqui o alfa vai de 0 a 100, a mesma escala em porcentagem que o resto do módulo usa para saturação e luminosidade, e não o 0–1 que o rgba() do CSS aceita.

Auxiliares de mistura e matemática de shaders

A matemática de mistura e de correção de cor que está por trás dos filtros de pós-processamento do ranuts/visual (o ColorAdjustFilter e companhia), exportada aqui para ser reaproveitada do lado da CPU (calcular a prévia de uma miniatura, digamos, sem levantar uma esteira de GPU). Diferente do resto do módulo, aqui os canais vão de 0 a 1, não de 0 a 255 nem de 0 a 100, seguindo a convenção dos shaders.

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

// Mistura em modo divisão duas cores de 0 a 1
const screened = blendScreen([0.8, 0.2, 0.1], [0.1, 0.5, 0.9]);

// Sobe o contraste e baixa um pouco o brilho
const graded = brightnessContrast([0.6, 0.6, 0.6], -0.05, 1.2);

// Colhe uma amostra de uma paleta de gradiente procedural em 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]);

// A matemática com gama correta (misturas, iluminação) deve acontecer em espaço linear
const linear = srgbToLinear(0.5);
const backToSrgb = linearToSrgb(linear); // ≈ 0.5

Padrões de formato

Expressões regulares para validar strings de cor. O RGB_REGEX e o RGBA_REGEX não toleram espaços; tire-os antes (value.replace(/\s+/g, '')).

FMT

Um registro de pares de códigos de escape ANSI para dar estilo e cor ao texto do terminal. Cada entrada é uma tupla [abrir, fechar] com que você embrulha uma string para estilizar a saída.

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

Chaves disponíveis: bold, dim, reset, italic, underline, inverse, hidden, strikethrough, black, red, green, yellow, blue, magenta, cyan, white, gray, e as variantes de fundo bgBlack, bgRed, bgGreen, bgYellow, bgBlue, bgMagenta, bgCyan, bgWhite.

Exemplo

Criar um Color

import { Color } from 'ranuts';

// A partir de uma string hexadecimal (forma curta ou longa, com ou sem #)
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 dos canais
const green = new Color(0, 255, 0);
console.log(green.hex); // '#00ff00'

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

Mexer num Color pelo HSL

import { Color } from 'ranuts';

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

color.setHue(120); // gira a matiz até o verde
console.log(color.rgb.toString()); // 'rgb(0,255,0)'

color.setLum(25); // mais escuro
color.setSat(50); // baixa a saturação
color.setAlpha(0.4);
console.log(color.rgba.toString()); // 'rgba(...,0.4)'

Montar uma paleta com o ColorScheme

import { ColorScheme } from 'ranuts';

// Par complementar a partir de uma cor base
const compl = ColorScheme.Compl('#3498db');
console.log(compl.palette.map((c) => c.hex));

// Esquema triádico (a base e duas cores afastadas 120°)
const triad = ColorScheme.Triad('#3498db');
console.log(triad.palette.length); // 3

// Direto de uma lista de cores
const custom = new ColorScheme(['#ff0000', '#00ff00', '#0000ff']);
console.log(custom.palette.map((c) => c.hsl.toString()));

Usar as funções de conversão

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'

// Onde está documentado, também se aceita um array como entrada
console.log(rgbToHsl([0, 128, 255])); // [h, s, l]

Estilizar a saída do terminal com o FMT

import { FMT } from 'ranuts';

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

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

Notas

1. Tudo é calculado de saída: um Color calcula todas as representações no construtor, então hex, rgb, rgba, hsl e hsla já nascem batendo entre si.
2. Os setters de HSL recalculam o RGB: setHue, setSat e setLum atualizam o HSL e depois tiram de novo o RGB e o hexadecimal pelo updateFromHsl. O setAlpha só mexe em rgba e hsla.
3. Entrada por array ou por canais: várias funções de conversão (rgbToHex, rgbToHsl, hslToRgb) aceitam tanto três canais soltos quanto um único array no primeiro argumento.
4. HSV e HSB: o hsvToRgb é outro nome do hsbToRgb, e o hsvToHsl outro nome da conversão de HSB para HSL. Aqui HSV e HSB são o mesmo modelo.
5. O FMT só vale no terminal: as sequências de escape ANSI aparecem como estilo apenas num terminal que as entenda; no console do navegador elas saem como caracteres de controle crus.