Color

Color parsing and interpolation utilities for Helios

RgbaColor

Interface representing a color in RGBA format.

interface RgbaColor {
  r: number;
  g: number;
  b: number;
  a: number;
}

r · number

Red component (0-255)

g · number

Green component (0-255)

b · number

Blue component (0-255)

a · number

Alpha component (0-1)

parseColor

Parses a color string into an RGBA object.

function parseColor(color: string): RgbaColor

color · string · required

Color string in hex, RGB/RGBA, or HSL/HSLA format

return · RgbaColor

Parsed color as an RGBA object

Supported formats

• Hex: #RGB, #RGBA, #RRGGBB, #RRGGBBAA
• RGB/RGBA: rgb(r, g, b), rgba(r, g, b, a)
• HSL/HSLA: hsl(h, s%, l%), hsla(h, s%, l%, a)

Example

import { parseColor } from '@helios-project/core';

// Hex formats
const red = parseColor('#f00');
const blue = parseColor('#0000ff');
const transparent = parseColor('#ff000080');

// RGB formats
const green = parseColor('rgb(0, 255, 0)');
const semiTransparent = parseColor('rgba(255, 0, 0, 0.5)');

// HSL formats
const yellow = parseColor('hsl(60, 100%, 50%)');
const purple = parseColor('hsla(270, 100%, 50%, 0.8)');

console.log(red); // { r: 255, g: 0, b: 0, a: 1 }

Errors

Throws HeliosError with code INVALID_COLOR_FORMAT if the color string is not in a supported format.

interpolateColors

Interpolates between colors based on an input value.

function interpolateColors(
  input: number,
  inputRange: number[],
  outputRange: string[],
  options?: InterpolateOptions
): string

input · number · required

The value to interpolate

inputRange · number[] · required

Array of input values (must be strictly monotonically increasing). Minimum 2 elements.

outputRange · string[] · required

Array of output color strings (must match length of inputRange). Colors can be in any supported format.

options · InterpolateOptions

Configuration for extrapolation and easing

return · string

Interpolated color as an RGBA string

Options

options.extrapolateLeft · 'extend' | 'clamp' | 'identity'

Behavior when input is less than the first inputRange value. Default: 'extend'

options.extrapolateRight · 'extend' | 'clamp' | 'identity'

Behavior when input is greater than the last inputRange value. Default: 'extend'

options.easing · (t: number) => number

Easing function to apply to the interpolation ratio

Example

import { interpolateColors } from '@helios-project/core';
import { easeInOut } from '@helios-project/core';

// Simple color transition
const color = interpolateColors(
  0.5,
  [0, 1],
  ['#ff0000', '#0000ff']
);
console.log(color); // 'rgba(127, 0, 127, 1)'

// Multi-stop gradient
const gradient = interpolateColors(
  50,
  [0, 50, 100],
  ['red', 'yellow', 'green']
);

// With easing
const smooth = interpolateColors(
  frame,
  [0, 60],
  ['#000', '#fff'],
  { easing: easeInOut }
);

// Clamp extrapolation
const clamped = interpolateColors(
  150,
  [0, 100],
  ['blue', 'red'],
  { extrapolateRight: 'clamp' }
); // Returns 'rgba(255, 0, 0, 1)' instead of extrapolating

Errors

Throws HeliosError with:

• INVALID_INPUT_RANGE if inputRange and outputRange lengths don’t match or have fewer than 2 elements
• UNSORTED_INPUT_RANGE if inputRange is not strictly monotonically increasing
• INVALID_COLOR_FORMAT if any color in outputRange cannot be parsed