Color Operations

/**
 * Get or set alpha channel
 * @param value - Alpha value (0-1), optional. If omitted, returns current alpha
 * @param mutate - Whether to mutate current instance (default: false)
 * @returns Color instance or current alpha value
 */
alpha(value?: number, mutate?: boolean): Color | number;

import chroma from "chroma-js";

const red = chroma('#FF0000');

// Get current alpha
console.log(red.alpha()); // 1

// Set alpha (returns new Color)
const semiRed = red.alpha(0.5);
console.log(semiRed.css()); // "rgba(255,0,0,0.5)"

// Mutate current instance
red.alpha(0.7, true);
console.log(red.alpha()); // 0.7

/**
 * Darken color in LAB space
 * @param amount - Amount to darken (default: 1)
 * @returns New darkened Color instance
 */
darken(amount?: number): Color;

/**
 * Alias for darken()
 */
darker(amount?: number): Color;

/**
 * Brighten color (equivalent to darken with negative amount)
 * @param amount - Amount to brighten (default: 1)
 * @returns New brightened Color instance
 */
brighten(amount?: number): Color;

/**
 * Alias for brighten()
 */
brighter(amount?: number): Color;

const blue = chroma('#0080FF');

// Darken by default amount (1)
const darker = blue.darken();

// Darken by specific amount
const muchDarker = blue.darken(2);

// Brighten
const lighter = blue.brighten();
const muchLighter = blue.brighten(3);

// Chain operations
const adjusted = blue.darken(0.5).brighten(0.2);

/**
 * Increase saturation in LCH space
 * @param amount - Amount to saturate (default: 1)
 * @returns New saturated Color instance
 */
saturate(amount?: number): Color;

/**
 * Decrease saturation (equivalent to saturate with negative amount)
 * @param amount - Amount to desaturate (default: 1)
 * @returns New desaturated Color instance
 */
desaturate(amount?: number): Color;

const color = chroma('#FF8080');

// Increase saturation
const vivid = color.saturate();
const moreVivid = color.saturate(2);

// Decrease saturation
const muted = color.desaturate();
const gray = color.desaturate(10); // Nearly grayscale

// Fine-tune saturation
const subtle = color.desaturate(0.3);

/**
 * Get or set luminance value
 * @param value - Luminance value (0-1), optional. If omitted, returns current luminance
 * @param mode - Color space for adjustment (default: 'rgb')
 * @returns Color instance or current luminance value
 */
luminance(value?: number, mode?: string): Color | number;

const red = chroma('#FF0000');
const blue = chroma('#0000FF');

// Get luminance values
console.log(red.luminance()); // ~0.2126
console.log(blue.luminance()); // ~0.0722

// Set specific luminance
const dimRed = red.luminance(0.1);
const brightBlue = blue.luminance(0.5);

// Useful for accessibility - ensure sufficient contrast
const background = chroma('#333333');
const text = background.luminance() < 0.5 ? 
  chroma('white') : chroma('black');

/**
 * Mix with another color
 * @param color - Color to mix with
 * @param ratio - Mix ratio (0-1, default: 0.5)
 * @param mode - Interpolation mode (default: 'lrgb')
 * @returns New mixed Color instance
 */
mix(color: Color | string, ratio?: number, mode?: string): Color;

/**
 * Alias for mix()
 */
interpolate(color: Color | string, ratio?: number, mode?: string): Color;

const red = chroma('#FF0000');
const blue = chroma('#0000FF');

// Equal mix (50/50)
const purple = red.mix(blue);

// Custom ratio
const redTinted = red.mix(blue, 0.2); // 80% red, 20% blue
const blueTinted = red.mix(blue, 0.8); // 20% red, 80% blue

// Different interpolation modes
const labMix = red.mix(blue, 0.5, 'lab');
const lchMix = red.mix(blue, 0.5, 'lch');
const hslMix = red.mix(blue, 0.5, 'hsl');

/**
 * Tint color with white
 * @param ratio - Tinting ratio (0-1, default: 0.5)
 * @param rest - Additional parameters passed to mix()
 * @returns New tinted Color instance
 */
tint(ratio?: number, ...rest: any[]): Color;

/**
 * Shade color with black
 * @param ratio - Shading ratio (0-1, default: 0.5)
 * @param rest - Additional parameters passed to mix()
 * @returns New shaded Color instance
 */
shade(ratio?: number, ...rest: any[]): Color;

const blue = chroma('#0080FF');

// Tint with white (lighter)
const lightBlue = blue.tint(); // 50% mix with white
const veryLightBlue = blue.tint(0.8); // 80% mix with white

// Shade with black (darker)
const darkBlue = blue.shade(); // 50% mix with black
const veryDarkBlue = blue.shade(0.8); // 80% mix with black

// Create color palette
const palette = [
  blue.shade(0.6),
  blue.shade(0.3),
  blue,
  blue.tint(0.3),
  blue.tint(0.6)
];

/**
 * Get specific channel value
 * @param channel - Channel specification (e.g., 'rgb.r', 'hsl.h', 'lab.l')
 * @returns Channel value
 */
get(channel: string): number;

/**
 * Set specific channel value
 * @param channel - Channel specification (e.g., 'rgb.r', 'hsl.h', 'lab.l')
 * @param value - New channel value
 * @param mutate - Whether to mutate current instance (default: false)
 * @returns New Color instance
 */
set(channel: string, value: number | string, mutate?: boolean): Color;

const color = chroma('#FF8040');

// Get channel values
console.log(color.get('rgb.r')); // 255
console.log(color.get('hsl.h')); // ~20
console.log(color.get('lab.l')); // ~70

// Set absolute channel values
const adjustedRed = color.set('rgb.r', 128);
const adjustedHue = color.set('hsl.h', 120);
const adjustedLightness = color.set('lab.l', 50);

// Use mathematical operators with strings
const brightened = color.set('lab.l', '+20'); // Increase lightness by 20
const desaturated = color.set('hsl.s', '*0.5'); // Half the saturation
const rotatedHue = color.set('hsl.h', '+180'); // Rotate hue by 180°
const dimmer = color.set('rgb.r', '/2'); // Half the red channel

// Multiple adjustments
const modified = color
  .set('hsl.s', '*0.8') // Reduce saturation to 80%
  .set('lab.l', '+10'); // Increase lightness by 10

/**
 * Premultiply alpha channel
 * @param mutate - Whether to mutate current instance (default: false)
 * @returns New premultiplied Color instance
 */
premultiply(mutate?: boolean): Color;

const semiRed = chroma.rgba(255, 0, 0, 0.5);

// Premultiply alpha
const premultiplied = semiRed.premultiply();

// RGB values are now multiplied by alpha
console.log(semiRed.rgb()); // [255, 0, 0, 0.5]
console.log(premultiplied.rgb()); // [127.5, 0, 0, 0.5]

/**
 * Check if color was clipped during conversion
 * @returns True if color was clipped, false otherwise
 */
clipped(): boolean;

// Colors outside RGB gamut may be clipped
const vividLab = chroma.lab(50, 100, 100);

if (vividLab.clipped()) {
  console.log('Color was clipped during RGB conversion');
}

// Check after operations
const brightened = chroma('#FF0000').brighten(5);
if (brightened.clipped()) {
  console.log('Brightening resulted in clipping');
}

/**
 * Premultiply RGB channels by alpha value
 * @param mutate - Whether to mutate current instance (default: false)
 * @returns Color instance with premultiplied RGB
 */
premultiply(mutate?: boolean): Color;

const semiRed = chroma.rgba(255, 0, 0, 0.5);

// Normal RGB values
console.log(semiRed.rgb()); // [255, 0, 0, 0.5]

// Premultiplied RGB values
const premultiplied = semiRed.premultiply();
console.log(premultiplied.rgb()); // [127.5, 0, 0, 0.5]

// Mutate current instance
semiRed.premultiply(true);
console.log(semiRed.rgb()); // [127.5, 0, 0, 0.5]