Color Functions

/**
 * Increases the lightness of a color by a specified amount
 * @param amount - Float between 0 and 1 representing the amount to lighten
 * @param color - Color string in any supported format
 * @returns Lightened color in same format as input
 */
function lighten(amount: number, color: string): string;

/**
 * Decreases the lightness of a color by a specified amount
 * @param amount - Float between 0 and 1 representing the amount to darken
 * @param color - Color string in any supported format
 * @returns Darkened color in same format as input
 */
function darken(amount: number, color: string): string;

/**
 * Increases the saturation of a color by a specified amount
 * @param amount - Float between 0 and 1 representing the amount to saturate
 * @param color - Color string in any supported format
 * @returns More saturated color in same format as input
 */
function saturate(amount: number, color: string): string;

/**
 * Decreases the saturation of a color by a specified amount
 * @param amount - Float between 0 and 1 representing the amount to desaturate
 * @param color - Color string in any supported format
 * @returns Less saturated color in same format as input
 */
function desaturate(amount: number, color: string): string;

/**
 * Adjusts the hue of a color by a specified number of degrees
 * @param degree - Number of degrees to adjust hue (-360 to 360)
 * @param color - Color string in any supported format
 * @returns Color with adjusted hue in same format as input
 */
function adjustHue(degree: number, color: string): string;

import { lighten, darken, saturate, desaturate, adjustHue } from "polished";

const baseColor = "#3498db";

// Lightness adjustments
const lighter = lighten(0.2, baseColor);  // "#5DADE2"
const darker = darken(0.15, baseColor);   // "#2E86C1"

// Saturation adjustments
const vibrant = saturate(0.3, baseColor);     // More vivid
const muted = desaturate(0.2, baseColor);     // More gray

// Hue rotation
const warmer = adjustHue(30, baseColor);      // More towards purple
const cooler = adjustHue(-30, baseColor);     // More towards cyan

/**
 * Mixes two colors together by a specified weight
 * @param weight - Float between 0 and 1, weight of first color in the mix
 * @param color - First color string
 * @param otherColor - Second color string
 * @returns Mixed color as string
 */
function mix(weight: number, color: string, otherColor: string): string;

/**
 * Returns the complement color (opposite on color wheel)
 * @param color - Color string in any supported format
 * @returns Complement color in same format as input
 */
function complement(color: string): string;

/**
 * Inverts a color (RGB inversion)
 * @param color - Color string in any supported format
 * @returns Inverted color in same format as input
 */
function invert(color: string): string;

/**
 * Converts a color to grayscale
 * @param color - Color string in any supported format
 * @returns Grayscale equivalent in same format as input
 */
function grayscale(color: string): string;

/**
 * Increases the opacity of a color
 * @param amount - Float between 0 and 1 representing the amount to increase opacity
 * @param color - Color string (supports alpha formats)
 * @returns Color with increased opacity
 */
function opacify(amount: number, color: string): string;

/**
 * Decreases the opacity of a color
 * @param amount - Float between 0 and 1 representing the amount to decrease opacity
 * @param color - Color string (supports alpha formats)
 * @returns Color with decreased opacity
 */
function transparentize(amount: number, color: string): string;

/**
 * Mixes a color with white to create a tint
 * @param amount - Float between 0 and 1 representing the amount of white to mix
 * @param color - Color string in any supported format
 * @returns Tinted color (lighter version)
 */
function tint(amount: number, color: string): string;

/**
 * Mixes a color with black to create a shade
 * @param amount - Float between 0 and 1 representing the amount of black to mix
 * @param color - Color string in any supported format
 * @returns Shaded color (darker version)
 */
function shade(amount: number, color: string): string;

/**
 * Creates an HSL color string
 * @param hue - Hue value (0-360)
 * @param saturation - Saturation as decimal (0-1)
 * @param lightness - Lightness as decimal (0-1)
 * @returns HSL color string
 */
function hsl(hue: number, saturation: number, lightness: number): string;

/**
 * Creates an HSLA color string with alpha
 * @param hue - Hue value (0-360)
 * @param saturation - Saturation as decimal (0-1)
 * @param lightness - Lightness as decimal (0-1)
 * @param alpha - Alpha as decimal (0-1)
 * @returns HSLA color string
 */
function hsla(hue: number, saturation: number, lightness: number, alpha: number): string;

/**
 * Creates an RGB color string
 * @param red - Red value (0-255)
 * @param green - Green value (0-255)
 * @param blue - Blue value (0-255)
 * @returns RGB color string
 */
function rgb(red: number, green: number, blue: number): string;

/**
 * Creates an RGBA color string with alpha
 * @param red - Red value (0-255)
 * @param green - Green value (0-255)
 * @param blue - Blue value (0-255)
 * @param alpha - Alpha as decimal (0-1)
 * @returns RGBA color string
 */
function rgba(red: number, green: number, blue: number, alpha: number): string;

/**
 * Gets the luminance value of a color
 * @param color - Color string in any supported format
 * @returns Luminance value as float (0-1)
 */
function getLuminance(color: string): number;

/**
 * Calculates the contrast ratio between two colors
 * @param color1 - First color string
 * @param color2 - Second color string
 * @returns Contrast ratio as float
 */
function getContrast(color1: string, color2: string): number;

/**
 * Checks if color combination meets WCAG contrast guidelines
 * @param color1 - First color string
 * @param color2 - Second color string
 * @returns Object with accessibility compliance information
 */
function meetsContrastGuidelines(color1: string, color2: string): ContrastScore;

/**
 * Returns the best contrasting color (black or white) for readability
 * @param color - Background color string
 * @param returnIfLightColor - Color to return if background is light (default: black)
 * @param returnIfDarkColor - Color to return if background is dark (default: white)
 * @returns Contrasting color for optimal readability
 */
function readableColor(
  color: string,
  returnIfLightColor?: string,
  returnIfDarkColor?: string
): string;

/**
 * Parses a color string and returns HSL values
 * @param color - Color string in any supported format
 * @returns Object with hue, saturation, lightness, and alpha properties
 */
function parseToHsl(color: string): HslColor;

/**
 * Parses a color string and returns RGB values
 * @param color - Color string in any supported format
 * @returns Object with red, green, blue, and alpha properties
 */
function parseToRgb(color: string): RgbColor;

/**
 * Converts HSL color object to color string
 * @param hslColor - HSL color object
 * @returns Color string representation
 */
function hslToColorString(hslColor: HslColor): string;

/**
 * Converts RGB color object to color string
 * @param rgbColor - RGB color object
 * @returns Color string representation
 */
function rgbToColorString(rgbColor: RgbColor): string;

/**
 * Converts a color to its optimal string representation
 * @param color - Color string or object
 * @returns Optimized color string (shortest valid format)
 */
function toColorString(color: string | RgbColor | HslColor): string;

/**
 * Sets the hue of a color to a specific value
 * @param hue - New hue value (0-360)
 * @param color - Color string in any supported format
 * @returns Color with new hue in same format as input
 */
function setHue(hue: number, color: string): string;

/**
 * Sets the lightness of a color to a specific value
 * @param lightness - New lightness value (0-1)
 * @param color - Color string in any supported format
 * @returns Color with new lightness in same format as input
 */
function setLightness(lightness: number, color: string): string;

/**
 * Sets the saturation of a color to a specific value
 * @param saturation - New saturation value (0-1)
 * @param color - Color string in any supported format
 * @returns Color with new saturation in same format as input
 */
function setSaturation(saturation: number, color: string): string;

interface HslColor {
  hue: number;
  saturation: number;
  lightness: number;
  alpha?: number;
}

interface RgbColor {
  red: number;
  green: number;
  blue: number;
  alpha?: number;
}

interface ContrastScore {
  AA: boolean;
  AAA: boolean;
  AALarge: boolean;
  AAALarge: boolean;
}