Raxol.Terminal.Color.TrueColor (Raxol v2.0.1)

View Source

True color (24-bit RGB) support for Raxol terminal applications.

This module provides comprehensive 24-bit RGB color handling with:

  • Full 16.7 million color support
  • Color space conversions (RGB, HSL, HSV, Lab)
  • Color manipulation and blending
  • Accessibility features (contrast checking, colorblind-friendly palettes)
  • Terminal capability detection
  • Graceful fallbacks to 256-color and 16-color modes
  • Color palette management and theming

Usage

# Create colors
red = TrueColor.rgb(255, 0, 0)
blue = TrueColor.hex("#0066CC")
green = TrueColor.hsl(120, 100, 50)

# Generate ANSI escape sequences
TrueColor.to_ansi_fg(red)  # ""
TrueColor.to_ansi_bg(blue) # ""

# Color manipulation
darker = TrueColor.darken(red, 0.2)
lighter = TrueColor.lighten(blue, 0.3)
mixed = TrueColor.mix(red, blue, 0.5)

# Accessibility
contrast = TrueColor.contrast_ratio(red, blue)
accessible? = TrueColor.wcag_compliant?(red, blue, :aa)

Summary

Types

alpha_component()
color_format()
hue()
lightness()
percentage()
rgb_component()
saturation()
t()
terminal_capability()
wcag_level()

Functions

accessible_palette(base_color, level \\ :aa)

Creates an accessible color palette that meets WCAG guidelines.

analogous(color, count \\ 5)

Creates an analogous color scheme (adjacent colors on wheel).

best_contrast(bg_color)

Finds the best contrasting color (black or white) for the given background.

complement(color)

Creates a complementary color (opposite on color wheel).

contrast_ratio(color1, color2)

Calculates the contrast ratio between two colors according to WCAG guidelines.

darken(color, percentage)

Darkens a color by the specified percentage.

desaturate(color, percentage)

Desaturates a color by the specified percentage.

detect_terminal_capability()

Detects the terminal's color capability.

generate_palette(base_color, scheme \\ :monochromatic)

Generates a color palette based on a base color.

hex(hex_string)

Creates a true color from a hex string.

hsl(h, s, l, a \\ 100)

Creates a true color from HSL values.

hsv(h, s, v, a \\ 100)

Creates a true color from HSV values.

lighten(color, percentage)

Lightens a color by the specified percentage.

mix(color1, color2, ratio)

Mixes two colors together by the specified ratio.

named(color_name)

Creates a true color from a predefined color name.

rgb(r, g, b, a \\ 255)

Creates a true color from RGB values.

saturate(color, percentage)

Saturates a color by the specified percentage.

supports_16_color?()

Checks if the terminal supports 16 colors.

supports_256_color?()

Checks if the terminal supports 256 colors.

supports_true_color?()

Checks if the terminal supports true color (24-bit).

to_ansi_16_bg(color)
to_ansi_16_fg(color)

Converts a true color to 16-color ANSI escape sequence (fallback).

to_ansi_256_bg(color)
to_ansi_256_fg(color)

Converts a true color to 256-color ANSI escape sequence (fallback).

to_ansi_auto_bg(color)
to_ansi_auto_fg(color)

Automatically selects the best ANSI escape sequence based on terminal capability.

to_ansi_bg(true_color)

Converts a true color to ANSI background escape sequence.

to_ansi_fg(true_color)

Converts a true color to ANSI foreground escape sequence.

to_hex(true_color)

Converts a true color to hex string.

to_hsl(true_color)

Converts a true color to HSL representation.

to_hsv(true_color)

Converts a true color to HSV representation.

to_lab(color)

Converts a true color to Lab color space (perceptually uniform).

triadic(color)

Creates a triadic color scheme (3 colors evenly spaced).

wcag_compliant?(fg, bg, level, large_text \\ false)

Checks if two colors meet WCAG contrast requirements.

Types

alpha_component()

@type alpha_component() :: 0..255

color_format()

@type color_format() :: :rgb | :hex | :hsl | :hsv | :lab | :ansi

hue()

@type hue() :: 0..360

lightness()

@type lightness() :: 0..100

percentage()

@type percentage() :: float()

rgb_component()

@type rgb_component() :: 0..255

saturation()

@type saturation() :: 0..100

t()

@type t() :: %Raxol.Terminal.Color.TrueColor{
  a: alpha_component(),
  b: rgb_component(),
  g: rgb_component(),
  r: rgb_component()
}

terminal_capability()

@type terminal_capability() :: :true_color | :color_256 | :color_16 | :monochrome

wcag_level()

@type wcag_level() :: :aa | :aaa

Functions

accessible_palette(base_color, level \\ :aa)

Creates an accessible color palette that meets WCAG guidelines.

analogous(color, count \\ 5)

Creates an analogous color scheme (adjacent colors on wheel).

best_contrast(bg_color)

Finds the best contrasting color (black or white) for the given background.

complement(color)

Creates a complementary color (opposite on color wheel).

contrast_ratio(color1, color2)

Calculates the contrast ratio between two colors according to WCAG guidelines.

Returns a value between 1 and 21, where 21 is maximum contrast (black/white).

darken(color, percentage)

Darkens a color by the specified percentage.

desaturate(color, percentage)

Desaturates a color by the specified percentage.

detect_terminal_capability()

Detects the terminal's color capability.

generate_palette(base_color, scheme \\ :monochromatic)

Generates a color palette based on a base color.

hex(hex_string)

Creates a true color from a hex string.

Examples

iex> TrueColor.hex("#FF0000")
%TrueColor{r: 255, g: 0, b: 0, a: 255}

iex> TrueColor.hex("0066CC")
%TrueColor{r: 0, g: 102, b: 204, a: 255}

iex> TrueColor.hex("#FF0000AA")
%TrueColor{r: 255, g: 0, b: 0, a: 170}

hsl(h, s, l, a \\ 100)

Creates a true color from HSL values.

Examples

iex> TrueColor.hsl(0, 100, 50)    # Pure red
%TrueColor{r: 255, g: 0, b: 0, a: 255}

iex> TrueColor.hsl(120, 100, 50)  # Pure green
%TrueColor{r: 0, g: 255, b: 0, a: 255}

hsv(h, s, v, a \\ 100)

Creates a true color from HSV values.

Examples

iex> TrueColor.hsv(0, 100, 100)   # Pure red
%TrueColor{r: 255, g: 0, b: 0, a: 255}

lighten(color, percentage)

Lightens a color by the specified percentage.

Examples

iex> red = TrueColor.rgb(255, 0, 0)
iex> TrueColor.lighten(red, 0.2)
# Returns lighter red

mix(color1, color2, ratio)

Mixes two colors together by the specified ratio.

Examples

iex> red = TrueColor.rgb(255, 0, 0)
iex> blue = TrueColor.rgb(0, 0, 255)
iex> TrueColor.mix(red, blue, 0.5)
# Returns purple (50% red, 50% blue)

named(color_name)

Creates a true color from a predefined color name.

Examples

iex> TrueColor.named(:red)
%TrueColor{r: 255, g: 0, b: 0, a: 255}

iex> TrueColor.named("blue")
%TrueColor{r: 0, g: 0, b: 255, a: 255}

rgb(r, g, b, a \\ 255)

Creates a true color from RGB values.

Examples

iex> TrueColor.rgb(255, 0, 0)
%TrueColor{r: 255, g: 0, b: 0, a: 255}

iex> TrueColor.rgb(128, 128, 128, 128)
%TrueColor{r: 128, g: 128, b: 128, a: 128}

saturate(color, percentage)

Saturates a color by the specified percentage.

supports_16_color?()

Checks if the terminal supports 16 colors.

supports_256_color?()

Checks if the terminal supports 256 colors.

supports_true_color?()

Checks if the terminal supports true color (24-bit).

to_ansi_16_bg(color)

to_ansi_16_fg(color)

Converts a true color to 16-color ANSI escape sequence (fallback).

to_ansi_256_bg(color)

to_ansi_256_fg(color)

Converts a true color to 256-color ANSI escape sequence (fallback).

to_ansi_auto_bg(color)

to_ansi_auto_fg(color)

Automatically selects the best ANSI escape sequence based on terminal capability.

to_ansi_bg(true_color)

Converts a true color to ANSI background escape sequence.

Examples

iex> blue = TrueColor.rgb(0, 0, 255)
iex> TrueColor.to_ansi_bg(blue)
"\e[48;2;0;0;255m"

to_ansi_fg(true_color)

Converts a true color to ANSI foreground escape sequence.

Examples

iex> red = TrueColor.rgb(255, 0, 0)
iex> TrueColor.to_ansi_fg(red)
"\e[38;2;255;0;0m"

to_hex(true_color)

Converts a true color to hex string.

Examples

iex> red = TrueColor.rgb(255, 0, 0)
iex> TrueColor.to_hex(red)
"#FF0000"

to_hsl(true_color)

Converts a true color to HSL representation.

Returns {hue, saturation, lightness} where:

  • hue is 0-360
  • saturation is 0-100
  • lightness is 0-100

to_hsv(true_color)

Converts a true color to HSV representation.

to_lab(color)

Converts a true color to Lab color space (perceptually uniform).

triadic(color)

Creates a triadic color scheme (3 colors evenly spaced).

wcag_compliant?(fg, bg, level, large_text \\ false)

Checks if two colors meet WCAG contrast requirements.

Examples

iex> black = TrueColor.rgb(0, 0, 0)
iex> white = TrueColor.rgb(255, 255, 255)
iex> TrueColor.wcag_compliant?(black, white, :aa)
true