@trishchuk/coolors-mcp 1.0.0

package/dist/color/index.d.ts

@@ -0,0 +1,716 @@
+/**
+ * Color type definitions for various color spaces
+ */
+/**
+ * Supported color formats for parsing
+ */
+declare enum ColorFormat {
+    HEX = "hex",
+    HSL = "hsl",
+    HSV = "hsv",
+    LAB = "lab",
+    RGB = "rgb",
+    XYZ = "xyz"
+}
+/**
+ * Options for color distance calculations
+ */
+interface ColorDistanceOptions {
+    /**
+     * Parameters for Delta E 94
+     */
+    deltaE94?: {
+        kC?: number;
+        kH?: number;
+        kL?: number;
+    };
+    /**
+     * Type of distance metric to use
+     */
+    metric?: "deltaE2000" | "deltaE76" | "deltaE94" | "euclidean" | "weighted";
+    /**
+     * Weights for weighted RGB distance
+     */
+    weights?: {
+        b?: number;
+        g?: number;
+        r?: number;
+    };
+}
+/**
+ * Color input type that can be parsed
+ */
+type ColorInput = HSL | HSV | LAB | RGB | string | XYZ;
+/**
+ * HCT (Hue, Chroma, Tone) color representation
+ */
+interface HCT$1 {
+    c: number;
+    h: number;
+    t: number;
+}
+/**
+ * Hexadecimal color representation
+ */
+type HEX = string;
+/**
+ * HSL (Hue, Saturation, Lightness) color representation
+ * h: [0, 360] degrees
+ * s: [0, 100] percentage
+ * l: [0, 100] percentage
+ */
+interface HSL {
+    h: number;
+    l: number;
+    s: number;
+}
+/**
+ * HSV (Hue, Saturation, Value) color representation
+ * Also known as HSB (Hue, Saturation, Brightness)
+ * h: [0, 360] degrees
+ * s: [0, 100] percentage
+ * v: [0, 100] percentage
+ */
+interface HSV {
+    h: number;
+    s: number;
+    v: number;
+}
+/**
+ * LAB color space (CIE L*a*b*)
+ * L: [0, 100] lightness
+ * a: [-128, 127] green-red axis
+ * b: [-128, 127] blue-yellow axis
+ */
+interface LAB {
+    a: number;
+    b: number;
+    l: number;
+}
+/**
+ * Color parsing result
+ */
+interface ParsedColor {
+    format: ColorFormat;
+    value: HSL | HSV | LAB | RGB | XYZ;
+}
+/**
+ * RGB color representation
+ * Values should be in range [0, 255]
+ */
+interface RGB {
+    b: number;
+    g: number;
+    r: number;
+}
+/**
+ * XYZ color space (CIE 1931)
+ * Reference white: D65 illuminant
+ */
+interface XYZ {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Constants for color space conversions
+ */
+declare const ColorConstants: {
+    /**
+     * D65 illuminant reference white point
+     */
+    readonly D65: {
+        readonly X: 95.047;
+        readonly Y: 100;
+        readonly Z: 108.883;
+    };
+    /**
+     * Epsilon for LAB conversion
+     */
+    readonly EPSILON: 0.008856;
+    /**
+     * Kappa for LAB conversion
+     */
+    readonly KAPPA: 903.3;
+};
+
+/**
+ * Color space conversion functions
+ */
+
+/**
+ * Convert ARGB format to RGB
+ */
+declare function argbToRgb(argb: number): RGB;
+/**
+ * Convert hexadecimal to RGB color
+ */
+declare function hexToRgb(hex: HEX): RGB;
+/**
+ * Convert HSL to RGB color space
+ */
+declare function hslToRgb(hsl: HSL): RGB;
+/**
+ * Convert HSV to RGB color space
+ */
+declare function hsvToRgb(hsv: HSV): RGB;
+/**
+ * Convert LAB to RGB color space
+ */
+declare function labToRgb(lab: LAB): RGB;
+/**
+ * Convert LAB to XYZ color space
+ */
+declare function labToXyz(lab: LAB): XYZ;
+/**
+ * Parse color string to RGB
+ * Supports: hex (#fff, #ffffff), rgb(r,g,b), hsl(h,s,l)
+ */
+declare function parseColor(color: string): null | RGB;
+/**
+ * Convert RGB to ARGB format (32-bit integer)
+ */
+declare function rgbToArgb(rgb: RGB): number;
+/**
+ * Convert RGB to hexadecimal color
+ */
+declare function rgbToHex(rgb: RGB): HEX;
+/**
+ * Convert RGB to HSL color space
+ */
+declare function rgbToHsl(rgb: RGB): HSL;
+/**
+ * Convert RGB to HSV color space
+ */
+declare function rgbToHsv(rgb: RGB): HSV;
+/**
+ * Convert RGB to LAB color space
+ */
+declare function rgbToLab(rgb: RGB): LAB;
+/**
+ * Convert RGB to XYZ color space
+ * Using sRGB working space and D65 illuminant
+ */
+declare function rgbToXyz(rgb: RGB): XYZ;
+/**
+ * Convert XYZ to LAB color space
+ * Using D65 illuminant
+ */
+declare function xyzToLab(xyz: XYZ): LAB;
+/**
+ * Convert XYZ to RGB color space
+ */
+declare function xyzToRgb(xyz: XYZ): RGB;
+
+/**
+ * HCT Class wrapper for Material Color Utilities compatibility
+ */
+/**
+ * HCT class compatible with Material Color Utilities
+ */
+declare class Hct {
+    get chroma(): number;
+    /**
+     * Set the chroma of this color. Chroma may decrease because chroma has a
+     * different maximum for any given hue and tone.
+     * @param newChroma 0 <= newChroma < ?
+     */
+    set chroma(newChroma: number);
+    get hue(): number;
+    /**
+     * Set the hue of this color. Chroma may decrease because chroma has a
+     * different maximum for any given hue and tone.
+     * @param newHue 0 <= newHue < 360; invalid values are corrected.
+     */
+    set hue(newHue: number);
+    get tone(): number;
+    /**
+     * Set the tone of this color. Chroma may decrease because chroma has a
+     * different maximum for any given hue and tone.
+     * @param newTone 0 <= newTone <= 100; invalid values are corrected.
+     */
+    set tone(newTone: number);
+    private _argb;
+    private _chroma;
+    private _hue;
+    private _tone;
+    private constructor();
+    /**
+     * Create an HCT color from hue, chroma, and tone.
+     * @param hue 0 <= hue < 360; invalid values are corrected.
+     * @param chroma 0 <= chroma < ?; Chroma may decrease because chroma has a
+     *     different maximum for any given hue and tone.
+     * @param tone 0 <= tone <= 100; invalid values are corrected.
+     * @return HCT representation of a color in default viewing conditions.
+     */
+    static from(hue: number, chroma: number, tone: number): Hct;
+    /**
+     * Create an HCT color from a color.
+     * @param argb ARGB representation of a color.
+     * @return HCT representation of a color in default viewing conditions
+     */
+    static fromInt(argb: number): Hct;
+    /**
+     * @return ARGB representation of an HCT color.
+     */
+    toInt(): number;
+}
+
+/**
+ * Check and/or fix universally disliked colors.
+ *
+ * Color science studies of color preference indicate universal distaste for
+ * dark yellow-greens, and also show this is correlated to distaste for
+ * biological waste and rotting food.
+ *
+ * See Palmer and Schloss, 2010 or Schloss and Palmer's Chapter 21 in Handbook
+ * of Color Psychology (2015).
+ */
+declare class DislikeAnalyzer {
+    /**
+     * Analyze a batch of colors and return statistics
+     * @param colors Array of HCT colors
+     * @return Statistics about disliked colors
+     */
+    static analyzeBatch(colors: Hct[]): {
+        disliked: number;
+        dislikedIndices: number[];
+        percentage: number;
+        total: number;
+    };
+    /**
+     * Fix all disliked colors in a batch
+     * @param colors Array of HCT colors
+     * @return Array with disliked colors fixed
+     */
+    static fixBatch(colors: Hct[]): Hct[];
+    /**
+     * If a color is disliked, lighten it to make it likable.
+     *
+     * @param hct A color to be judged.
+     * @return A new color if the original color is disliked, or the original
+     *   color if it is acceptable.
+     */
+    static fixIfDisliked(hct: Hct): Hct;
+    /**
+     * Fix a hex color if it's disliked
+     * @param hex Hex color string
+     * @return Fixed hex color or original if not disliked
+     */
+    static fixIfDislikedHex(hex: string): string;
+    /**
+     * Returns true if a color is disliked.
+     *
+     * @param hct A color to be judged.
+     * @return Whether the color is disliked.
+     *
+     * Disliked is defined as a dark yellow-green that is not neutral.
+     * Specifically: hue 90-111°, chroma > 16, tone < 65
+     */
+    static isDisliked(hct: Hct): boolean;
+    /**
+     * Check if a color is in the "bile zone" - universally disliked colors
+     * @param hex Hex color string
+     * @return Whether the color is disliked
+     */
+    static isDislikedHex(hex: string): boolean;
+}
+
+/**
+ * Color Harmonization
+ * Algorithms to blend and harmonize colors based on Material Design principles
+ */
+
+/**
+ * Temperature-based color adjustment
+ * Warmer (positive) or cooler (negative) adjustment
+ */
+declare function adjustTemperature(color: RGB, amount: number): RGB;
+/**
+ * Find analogous colors (adjacent on color wheel)
+ */
+declare function analogous(color: RGB, angle?: number, count?: number): RGB[];
+/**
+ * Blend two colors in HCT space
+ * More perceptually uniform than RGB blending
+ */
+declare function blend(from: RGB, to: RGB, amount: number): RGB;
+/**
+ * Create a double complementary (rectangle) scheme
+ */
+declare function doubleComplementary(color1: RGB, color2: RGB): [RGB, RGB, RGB, RGB];
+/**
+ * Create a gradient between two colors
+ */
+declare function gradient(from: RGB, to: RGB, steps: number): RGB[];
+/**
+ * Harmonize a color with a target, making them work better together
+ * Based on Material's blend algorithm
+ */
+declare function harmonize(design: RGB, source: RGB, factor?: number): RGB;
+/**
+ * Find split-complementary colors
+ */
+declare function splitComplementary(color: RGB, angle?: number): [RGB, RGB, RGB];
+/**
+ * Find tetradic (square) colors - four colors evenly spaced
+ */
+declare function tetradic(color: RGB): [RGB, RGB, RGB, RGB];
+
+/**
+ * HCT (Hue, Chroma, Tone) color space types
+ * Based on Material Color Utilities
+ */
+/**
+ * CAM16 color appearance model
+ * Predicts color appearance under different viewing conditions
+ */
+interface CAM16 {
+    /** Chroma composition */
+    astar: number;
+    /** Brightness composition */
+    bstar: number;
+    /** Chroma */
+    chroma: number;
+    /** Hue angle */
+    hue: number;
+    /** Lightness */
+    j: number;
+    /** Hue composition */
+    jstar: number;
+    /** Colorfulness */
+    m: number;
+    /** Brightness */
+    q: number;
+    /** Saturation */
+    s: number;
+}
+/**
+ * HCT color representation
+ * A perceptually accurate color space that combines:
+ * - Hue from CAM16
+ * - Chroma from CAM16
+ * - Tone (Lightness) from L* (LAB)
+ */
+interface HCT {
+    /** Chroma (colorfulness) [0, ~150] - actual max varies by hue and tone */
+    c: number;
+    /** Hue angle in degrees [0, 360) */
+    h: number;
+    /** Tone (lightness) [0, 100] */
+    t: number;
+}
+/**
+ * Viewing conditions for CAM16
+ * Describes the environment in which colors are viewed
+ */
+interface ViewingConditions {
+    /** Background luminance ratio */
+    aw: number;
+    /** Base exponential nonlinearity */
+    c: number;
+    /** Degree of adaptation */
+    fl: number;
+    /** Luminance level adaptation factor */
+    flRoot: number;
+    /** Adapting luminance */
+    n: number;
+    /** Luminance level adaptation factor */
+    nbb: number;
+    /** Chromatic induction factor */
+    nc: number;
+    /** Chromatic induction factor */
+    ncb: number;
+    /** Achromatic response for white */
+    rgbD: [number, number, number];
+    /** Surround factor */
+    z: number;
+}
+/**
+ * Standard viewing conditions
+ */
+declare const STANDARD_CONDITIONS: ViewingConditions;
+
+/**
+ * HCT Solver - Converts between HCT and RGB color spaces
+ * Based on Material Color Utilities algorithms
+ */
+
+/**
+ * Create an HCT color from components
+ */
+declare function hct(hue: number, chroma: number, tone: number): HCT;
+/**
+ * Convert HCT to RGB using iterative solving
+ * This is a simplified version of Material's HCT solver
+ */
+declare function hctToRgb(hct: HCT): RGB;
+/**
+ * Get maximum chroma for a given hue and tone
+ * This is an approximation - actual max varies
+ */
+declare function maxChroma(hue: number, tone: number): number;
+/**
+ * Convert RGB to HCT
+ */
+declare function rgbToHct(rgb: RGB): HCT;
+
+/**
+ * Tonal Palette Generator
+ * Creates Material Design 3 tonal palettes from HCT colors
+ */
+
+/**
+ * Standard Material 3 tone values
+ */
+declare const MATERIAL_TONES: readonly [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100];
+/**
+ * Extended tone values for more granularity
+ */
+declare const EXTENDED_TONES: readonly [0, 5, 10, 15, 20, 25, 30, 35, 40, 45, 50, 55, 60, 65, 70, 75, 80, 85, 90, 92, 94, 96, 98, 99, 100];
+/**
+ * Material 3 Core Palette
+ * Contains all the tonal palettes needed for a complete theme
+ */
+interface CorePalette {
+    /** Error color palette */
+    error: TonalPalette;
+    /** Neutral color palette (grays) */
+    neutral: TonalPalette;
+    /** Neutral variant palette (slightly tinted grays) */
+    neutralVariant: TonalPalette;
+    /** Primary color palette */
+    primary: TonalPalette;
+    /** Secondary color palette */
+    secondary: TonalPalette;
+    /** Tertiary color palette */
+    tertiary: TonalPalette;
+}
+/**
+ * A tonal palette - variations of a single color at different tones
+ */
+declare class TonalPalette {
+    readonly hue: number;
+    readonly chroma: number;
+    /**
+     * Get extended tones for more options
+     */
+    get extendedTones(): Record<number, RGB>;
+    /**
+     * Get all Material 3 standard tones
+     */
+    get materialTones(): Record<number, RGB>;
+    private cache;
+    constructor(hue: number, chroma: number);
+    /**
+     * Create a tonal palette from an HCT color
+     */
+    static fromHct(color: HCT): TonalPalette;
+    /**
+     * Create a tonal palette from an RGB color
+     */
+    static fromRgb(rgb: RGB): TonalPalette;
+    /**
+     * Get the color at a specific tone
+     */
+    tone(tone: number): RGB;
+}
+/**
+ * Generate an analogous palette (adjacent hues)
+ */
+declare function analogousPalette(source: RGB, count?: number, hueShift?: number): TonalPalette[];
+/**
+ * Generate a complementary palette
+ */
+declare function complementaryPalette(source: RGB): [TonalPalette, TonalPalette];
+/**
+ * Generate a complete Material 3 core palette from a source color
+ */
+declare function corePaletteFromRgb(source: RGB): CorePalette;
+/**
+ * Generate a monochromatic palette (single hue, varying tones)
+ */
+declare function monochromaticPalette(source: RGB, tones?: readonly number[]): RGB[];
+/**
+ * Generate a triadic palette (three colors evenly spaced)
+ */
+declare function triadicPalette(source: RGB): [TonalPalette, TonalPalette, TonalPalette];
+
+/**
+ * Color distance metrics for calculating perceptual differences between colors
+ */
+
+/**
+ * Determine if two colors are perceptually similar
+ * Uses Delta E 2000 with a threshold
+ */
+declare function areColorsSimilar(color1: RGB, color2: RGB, threshold?: number): boolean;
+/**
+ * Calculate color distance between two RGB colors using specified metric
+ */
+declare function colorDistance(color1: RGB, color2: RGB, options?: ColorDistanceOptions): number;
+/**
+ * Calculate Delta E CIE2000 (ΔE*00)
+ * Most accurate perceptual color difference formula
+ */
+declare function deltaE2000(lab1: LAB, lab2: LAB): number;
+/**
+ * Calculate Delta E CIE76 (ΔE*ab)
+ * Original CIE color difference formula
+ */
+declare function deltaE76(lab1: LAB, lab2: LAB): number;
+/**
+ * Calculate Delta E CIE94 (ΔE*94)
+ * Improved perceptual uniformity over CIE76
+ */
+declare function deltaE94(lab1: LAB, lab2: LAB, options?: {
+    kC?: number;
+    kH?: number;
+    kL?: number;
+}): number;
+/**
+ * Calculate Euclidean distance between two RGB colors
+ * Simple but not perceptually uniform
+ */
+declare function euclideanDistance(color1: RGB, color2: RGB): number;
+/**
+ * Find the most different color from a set of colors
+ */
+declare function findMostDifferentColor(baseColor: RGB, colors: RGB[], options?: ColorDistanceOptions): null | RGB;
+/**
+ * Find the most similar color from a set of colors
+ */
+declare function findMostSimilarColor(baseColor: RGB, colors: RGB[], options?: ColorDistanceOptions): null | RGB;
+/**
+ * Calculate weighted RGB distance
+ * Better approximation of perceptual difference than simple Euclidean
+ */
+declare function weightedRgbDistance(color1: RGB, color2: RGB, weights?: {
+    b?: number;
+    g?: number;
+    r?: number;
+}): number;
+
+/**
+ * Utility functions for color manipulation and validation
+ */
+
+/**
+ * Clamp HSL values to valid range
+ */
+declare function clampHsl(hsl: HSL): HSL;
+/**
+ * Clamp HSV values to valid range
+ */
+declare function clampHsv(hsv: HSV): HSV;
+/**
+ * Clamp RGB values to valid range
+ */
+declare function clampRgb(rgb: RGB): RGB;
+/**
+ * Darken a color by a percentage
+ * @param rgb The color to darken
+ * @param amount Amount to darken (0-100)
+ */
+declare function darken(rgb: RGB, amount: number): RGB;
+/**
+ * Desaturate a color by a percentage
+ * @param rgb The color to desaturate
+ * @param amount Amount to desaturate (0-100)
+ */
+declare function desaturate(rgb: RGB, amount: number): RGB;
+/**
+ * Format color to various string representations
+ */
+declare function formatColor(rgb: RGB, format?: "hex" | "hsl" | "hsv" | "rgb"): string;
+/**
+ * Format HSL color to string
+ */
+declare function formatHsl(hsl: HSL, alpha?: number): string;
+/**
+ * Format RGB color to string
+ */
+declare function formatRgb(rgb: RGB, alpha?: number): string;
+/**
+ * Get complementary color (opposite on color wheel)
+ */
+declare function getComplementary(rgb: RGB): RGB;
+/**
+ * Calculate contrast ratio between two colors
+ * Based on WCAG 2.0 formula
+ */
+declare function getContrastRatio(color1: RGB, color2: RGB): number;
+/**
+ * Calculate relative luminance of an RGB color
+ * Based on WCAG 2.0 formula
+ */
+declare function getLuminance(rgb: RGB): number;
+/**
+ * Invert a color
+ */
+declare function invertColor(rgb: RGB): RGB;
+/**
+ * Check if a color is considered "dark"
+ * Based on luminance threshold
+ */
+declare function isDark(rgb: RGB, threshold?: number): boolean;
+/**
+ * Check if a color is considered "light"
+ * Based on luminance threshold
+ */
+declare function isLight(rgb: RGB, threshold?: number): boolean;
+/**
+ * Validate hexadecimal color string
+ */
+declare function isValidHex(hex: string): boolean;
+/**
+ * Validate HSL color values
+ */
+declare function isValidHsl(hsl: HSL): boolean;
+/**
+ * Validate HSV color values
+ */
+declare function isValidHsv(hsv: HSV): boolean;
+/**
+ * Validate RGB color values
+ */
+declare function isValidRgb(rgb: RGB): boolean;
+/**
+ * Lighten a color by a percentage
+ * @param rgb The color to lighten
+ * @param amount Amount to lighten (0-100)
+ */
+declare function lighten(rgb: RGB, amount: number): RGB;
+/**
+ * Check if contrast meets WCAG AA standard
+ * Normal text: 4.5:1, Large text: 3:1
+ */
+declare function meetsContrastAA(color1: RGB, color2: RGB, largeText?: boolean): boolean;
+/**
+ * Check if contrast meets WCAG AAA standard
+ * Normal text: 7:1, Large text: 4.5:1
+ */
+declare function meetsContrastAAA(color1: RGB, color2: RGB, largeText?: boolean): boolean;
+/**
+ * Mix two colors together
+ * @param color1 First color
+ * @param color2 Second color
+ * @param weight Weight of the first color (0-1)
+ */
+declare function mixColors(color1: RGB, color2: RGB, weight?: number): RGB;
+/**
+ * Generate a random RGB color
+ */
+declare function randomColor(): RGB;
+/**
+ * Saturate a color by a percentage
+ * @param rgb The color to saturate
+ * @param amount Amount to saturate (0-100)
+ */
+declare function saturate(rgb: RGB, amount: number): RGB;
+/**
+ * Convert color to grayscale
+ */
+declare function toGrayscale(rgb: RGB): RGB;
+
+export { type CAM16, ColorConstants, type ColorDistanceOptions, ColorFormat, type ColorInput, type CorePalette, DislikeAnalyzer, EXTENDED_TONES, type HCT$1 as HCT, type HEX, type HSL, type HSV, Hct, type LAB, MATERIAL_TONES, type ParsedColor, type RGB, STANDARD_CONDITIONS, TonalPalette, type ViewingConditions, type XYZ, adjustTemperature, analogous, analogousPalette, areColorsSimilar, argbToRgb, blend, clampHsl, clampHsv, clampRgb, colorDistance, complementaryPalette, corePaletteFromRgb, darken, deltaE2000, deltaE76, deltaE94, desaturate, doubleComplementary, euclideanDistance, findMostDifferentColor, findMostSimilarColor, formatColor, formatHsl, formatRgb, getComplementary, getContrastRatio, getLuminance, gradient, harmonize, hct, hctToRgb, hexToRgb, hslToRgb, hsvToRgb, invertColor, isDark, isLight, isValidHex, isValidHsl, isValidHsv, isValidRgb, labToRgb, labToXyz, lighten, maxChroma, meetsContrastAA, meetsContrastAAA, mixColors, monochromaticPalette, parseColor, randomColor, rgbToArgb, rgbToHct, rgbToHex, rgbToHsl, rgbToHsv, rgbToLab, rgbToXyz, saturate, splitComplementary, tetradic, toGrayscale, triadicPalette, weightedRgbDistance, xyzToLab, xyzToRgb };