contrastrast
Version:
A lightweight tool that parses color strings and recommends text contrast based on WCAG Standards
276 lines • 12.2 kB
TypeScript
import { type ContrastOptions, type ContrastResult } from "./utils/textContrast.js";
import type { HSLValues, RGBValues } from "./types/Colors.types.js";
import type { WCAGContrastLevel, WCAGTextSize } from "./types/WCAG.types.js";
import type { ParseOptions } from "./types/ParseOptions.types.js";
/**
* A comprehensive color manipulation class that supports parsing, conversion, and accessibility analysis
* @example
* ```typescript
* const color = new Contrastrast("#1a73e8");
* const isLight = color.isLight(); // false
* const hexValue = color.toHex(); // "#1a73e8"
* const ratio = color.contrastRatio("#ffffff"); // 4.5
* ```
*/
export declare class Contrastrast {
private readonly rgb;
/**
* Create a new Contrastrast instance from a color string
* @param colorString Color string in hex (#abc or #abcdef), rgb (rgb(r,g,b)), or hsl (hsl(h,s%,l%)) format
* @param parseOpts Optional parsing configuration
* @param parseOpts.throwOnError Whether to throw an error on invalid color strings (default: true)
* @param parseOpts.fallbackColor Fallback color to use when throwOnError is false (default: "#000000")
* @throws {Error} When the color string format is not supported and throwOnError is true
* @example
* ```typescript
* const color1 = new Contrastrast("#ff0000");
* const color2 = new Contrastrast("rgb(255, 0, 0)");
* const color3 = new Contrastrast("hsl(0, 100%, 50%)");
*
* // With error handling
* const color4 = new Contrastrast("invalid", { throwOnError: false, fallbackColor: "#333333" });
* ```
*/
constructor(colorString: string, parseOpts?: Partial<ParseOptions>);
/**
* Create a Contrastrast instance from a hex color string
* @param hex Hex color string with or without # prefix (e.g., "#ff0000" or "ff0000")
* @returns New Contrastrast instance
* @example
* ```typescript
* const red1 = Contrastrast.fromHex("#ff0000");
* const red2 = Contrastrast.fromHex("ff0000");
* const shortRed = Contrastrast.fromHex("#f00");
* ```
*/
static fromHex: (hex: string) => Contrastrast;
/**
* Create a Contrastrast instance from RGB values as separate parameters
* @param r Red value (0-255)
* @param g Green value (0-255)
* @param b Blue value (0-255)
* @returns New Contrastrast instance
*/
static fromRgb(r: number, g: number, b: number): Contrastrast;
/**
* Create a Contrastrast instance from an RGB values object
* @param rgb RGB values object with r, g, b properties
* @returns New Contrastrast instance
*/
static fromRgb(rgb: RGBValues): Contrastrast;
/**
* Create a Contrastrast instance from HSL values as separate parameters
* @param h Hue value (0-360 degrees)
* @param s Saturation value (0-100 percent)
* @param l Lightness value (0-100 percent)
* @returns New Contrastrast instance
*/
static fromHsl(h: number, s: number, l: number): Contrastrast;
/**
* Create a Contrastrast instance from an HSL values object
* @param hsl HSL values object with h, s, l properties
* @returns New Contrastrast instance
*/
static fromHsl(hsl: HSLValues): Contrastrast;
/**
* Parse a color string into a Contrastrast instance (alias for constructor)
* @param colorString Color string in hex, rgb, or hsl format
* @param parseOpts Optional parsing configuration
* @param parseOpts.throwOnError Whether to throw an error on invalid color strings (default: true)
* @param parseOpts.fallbackColor Fallback color to use when throwOnError is false (default: "#000000")
* @returns New Contrastrast instance
* @throws {Error} When the color string format is not supported and throwOnError is true
* @example
* ```typescript
* const color = Contrastrast.parse("#1a73e8");
*
* // With error handling
* const safeColor = Contrastrast.parse("invalid", { throwOnError: false, fallbackColor: "#ffffff" });
* ```
*/
static parse: (colorString: string, parseOpts?: Partial<ParseOptions>) => Contrastrast;
/**
* Convert the color to a hex string representation
* @param includeHash Whether to include the # prefix (default: true)
* @returns Hex color string (e.g., "#ff0000" or "ff0000")
* @example
* ```typescript
* const color = new Contrastrast("rgb(255, 0, 0)");
* const withHash = color.toHex(); // "#ff0000"
* const withoutHash = color.toHex(false); // "ff0000"
* ```
*/
toHex: (includeHash?: boolean) => string;
/**
* Get the RGB values as an object
* @returns RGB values object with r, g, b properties (0-255)
* @example
* ```typescript
* const color = new Contrastrast("#ff0000");
* const rgb = color.toRgb(); // { r: 255, g: 0, b: 0 }
* ```
*/
toRgb: () => RGBValues;
/**
* Convert the color to an RGB string representation
* @returns RGB color string (e.g., "rgb(255, 0, 0)")
* @example
* ```typescript
* const color = new Contrastrast("#ff0000");
* const rgbString = color.toRgbString(); // "rgb(255, 0, 0)"
* ```
*/
toRgbString: () => string;
/**
* Convert the color to HSL values
* @returns HSL values object with h (0-360), s (0-100), l (0-100) properties
* @example
* ```typescript
* const color = new Contrastrast("#ff0000");
* const hsl = color.toHsl(); // { h: 0, s: 100, l: 50 }
* ```
*/
toHsl: () => HSLValues;
/**
* Convert the color to an HSL string representation
* @returns HSL color string (e.g., "hsl(0, 100%, 50%)")
* @example
* ```typescript
* const color = new Contrastrast("#ff0000");
* const hslString = color.toHslString(); // "hsl(0, 100%, 50%)"
* ```
*/
toHslString: () => string;
/**
* Calculate the WCAG 2.1 relative luminance of the color
* @returns Luminance value between 0 (darkest) and 1 (lightest)
* @example
* ```typescript
* const black = new Contrastrast("#000000");
* const white = new Contrastrast("#ffffff");
* console.log(black.luminance()); // 0
* console.log(white.luminance()); // 1
* ```
*/
luminance: () => number;
/**
* Calculate the perceived brightness of the color using the WCAG formula
* @returns Brightness value between 0 (darkest) and 255 (brightest)
* @example
* ```typescript
* const color = new Contrastrast("#1a73e8");
* const brightness = color.brightness(); // ~102.4
* ```
*/
brightness: () => number;
/**
* Determine if the color is considered "light" based on WCAG brightness threshold
* @returns True if the color is light (brightness > 124), false otherwise
* @example
* ```typescript
* const lightColor = new Contrastrast("#ffffff");
* const darkColor = new Contrastrast("#000000");
* console.log(lightColor.isLight()); // true
* console.log(darkColor.isLight()); // false
* ```
*/
isLight: () => boolean;
/**
* Determine if the color is considered "dark" based on WCAG brightness threshold
* @returns True if the color is dark (brightness <= 124), false otherwise
* @example
* ```typescript
* const lightColor = new Contrastrast("#ffffff");
* const darkColor = new Contrastrast("#000000");
* console.log(lightColor.isDark()); // false
* console.log(darkColor.isDark()); // true
* ```
*/
isDark: () => boolean;
/**
* Calculate the WCAG 2.1 contrast ratio between this color and another color
* @param color Color to compare against - accepts hex, rgb, hsl strings or Contrastrast instance
* @returns Contrast ratio from 1:1 (no contrast) to 21:1 (maximum contrast)
* @example
* ```typescript
* const bgColor = new Contrastrast("#1a73e8");
* const ratio = bgColor.contrastRatio("#ffffff"); // 4.5
* ```
*/
contrastRatio: (color: Contrastrast | string) => number;
/**
* Calculate the contrast ratio between this color and another color
* @param comparisonColor Color to compare against - accepts hex, rgb, hsl strings or Contrastrast instance
* @param role Role of this color instance in the contrast calculation
* @returns Contrast ratio as a number (1:1 to 21:1)
* @example
* ```typescript
* const bgColor = new Contrastrast("#1a73e8");
* const ratio = bgColor.textContrast("#ffffff"); // 4.5 (current as background, white as foreground)
* const ratio2 = bgColor.textContrast("#ffffff", "foreground"); // 4.5 (current as foreground, white as background)
* ```
*/
textContrast(comparisonColor: Contrastrast | string, role?: "foreground" | "background"): number;
/**
* Analyze text contrast with detailed WCAG compliance results
* @param comparisonColor Color to compare against - accepts hex, rgb, hsl strings or Contrastrast instance
* @param role Role of this color instance in the contrast calculation
* @param options Configuration with returnDetails: true for detailed analysis
* @returns Detailed contrast analysis with WCAG compliance breakdown
* @example
* ```typescript
* const bgColor = new Contrastrast("#1a73e8");
* const result = bgColor.textContrast("#ffffff", "background", { returnDetails: true });
* // {
* // ratio: 4.5,
* // passes: {
* // AA_NORMAL: true, // 4.5 >= 4.5
* // AA_LARGE: true, // 4.5 >= 3.0
* // AAA_NORMAL: false, // 4.5 < 7.0
* // AAA_LARGE: true // 4.5 >= 4.5
* // }
* // }
* ```
*/
textContrast(comparisonColor: Contrastrast | string, role: "foreground" | "background", options: {
returnDetails: true;
}): ContrastResult;
/**
* Calculate the contrast ratio between this color and another color
* @param comparisonColor Color to compare against - accepts hex, rgb, hsl strings or Contrastrast instance
* @param role Role of this color instance in the contrast calculation
* @param options Configuration with returnDetails: false (default) for simple ratio
* @returns Contrast ratio as a number (1:1 to 21:1)
*/
textContrast(comparisonColor: Contrastrast | string, role?: "foreground" | "background", options?: ContrastOptions): number;
/**
* Check if the color combination meets specific WCAG contrast requirements
* @param comparisonColor Color to compare against - accepts hex, rgb, hsl strings or Contrastrast instance
* @param role Role of this color instance ("foreground" for text color, "background" for background color)
* @param targetWcagLevel Target WCAG compliance level ("AA" or "AAA")
* @param textSize Text size category ("normal" or "large") - affects required contrast ratio
* @returns True if the combination meets the specified WCAG requirements
* @example
* ```typescript
* const bgColor = new Contrastrast("#1a73e8");
* const meetsAA = bgColor.meetsWCAG("#ffffff", "background", "AA"); // true
* const meetsAAA = bgColor.meetsWCAG("#ffffff", "background", "AAA"); // false
* ```
*/
meetsWCAG: (comparisonColor: Contrastrast | string, role: "foreground" | "background", targetWcagLevel: WCAGContrastLevel, textSize?: WCAGTextSize) => boolean;
/**
* Check if this color is equal to another color (RGB values comparison)
* @param color Color to compare against - accepts hex, rgb, hsl strings or Contrastrast instance
* @returns True if both colors have identical RGB values
* @example
* ```typescript
* const color1 = new Contrastrast("#ff0000");
* const color2 = new Contrastrast("rgb(255, 0, 0)");
* const color3 = new Contrastrast("hsl(0, 100%, 50%)");
* console.log(color1.equals(color2)); // true
* console.log(color1.equals(color3)); // true
* ```
*/
equals: (color: Contrastrast | string) => boolean;
}
//# sourceMappingURL=contrastrast.d.ts.map