@patreon/studio/module/utilities/color/index.d.ts

Patreon Studio Design System

import type { HctInstance, HctaObject, HexString, HexString3, HexString6, HexString8 } from '~/types/color';
/**
 * Checks if a hex color is a 3 character hex string
 *
 * @param colorString - The hex color to check including the # symbol.
 * @returns True if the hex color is a 3 character hex string, false otherwise.
 */
export declare function isValidHex3(colorString: string): colorString is HexString3;
/**
 * Checks if a hex color is a 6 character hex string
 *
 * @param colorString - The hex color to check including the # symbol.
 * @returns True if the hex color is a 6 character hex string, false otherwise.
 */
export declare function isValidHex6(colorString: string): colorString is HexString6;
/**
 * Checks if a hex color is a 8 character hex string
 *
 * @param colorString - The hex color to check including the # symbol.
 * @returns True if the hex color is a 8 character hex string, false otherwise.
 */
export declare function isValidHex8(colorString: string): colorString is HexString8;
/**
 * Checks if a hex color is a valid hex color
 *
 * @param colorString - The hex color to check including the # symbol.
 * @returns True if the hex color is a valid hex color, false otherwise.
 */
export declare function isValidHex(colorString: string): colorString is HexString;
/**
 * Converts a hex color to an HCT instance
 *
 * @internal we don't intend to export this function because
 * we don't want to fully expose the internals the HCT class.
 *
 * @param hex - The hex color to convert (e.g. "#000000")
 * @returns An HCT color instance.
 */
export declare function hex2hctInstance(hex: HexString): HctInstance;
/**
 * Converts an HCT instance to a hex color
 *
 * @internal we don't intend to export this function because
 * we don't want to fully expose the internals the HCT class.
 *
 * @param hct - The HCT color instance to convert.
 * @returns The hex color.
 **/
export declare function hctInstance2hex(hct: HctInstance): HexString6;
/**
 * Converts an HCT instance to a HCTa object
 *
 * @param hct - The HCT color instance to convert.
 * @returns A HCTa object.
 */
export declare function hctInstance2hcta(hct: HctInstance): HctaObject;
/**
 * Converts a hex color to an HCTa color object
 *
 * @param hex - The hex color to convert (e.g. "#000000")
 * @returns An object with an HCT color instance and alpha value (0-1).
 **/
export declare function hex2hcta(hex: HexString): HctaObject;
/**
 * Generates a hex color from an HCTa object. A 6 or 8-digit hex string
 * color will be returned depending on whether the alpha is defined.
 *
 * @param hctaObject - The HCTa object to convert.
 * @returns a 6-digit or 8-digit hex color.
 */
export declare function hcta2hex(hctaObject: Omit<HctaObject, 'alpha'>): HexString6;
export declare function hcta2hex(hctaObject: Required<HctaObject>): HexString8;
/**
 * hello linear interpolation function, we call you lerp?
 *
 * @param x - The start value.
 * @param y - The end value.
 * @param a - The amount to interpolate between the start and end values.
 * @returns The interpolated value.
 */
export declare const lerp: (x: number, y: number, a: number) => number;
/**
 * Linearly interpolates between two colors in the HCT color space.
 *
 * @param startColor - The start color (6 or 8-digit hex string).
 * @param endColor - The end color (6 or 8-digit hex string).
 * @param a - Amount 0 - 1 between start and end.
 * @returns The interpolated color (6 or 8-digit hex string).
 */
export declare function lerpColor(startColor: HexString, endColor: HexString, a: number): HexString6 | HexString8;
/**
 * Calculates the distance between two hex colors using the
 * Hct color space.
 *
 * @param color1 - The first hex color.
 * @param color2 - The second hex color.
 * @returns The distance between the two colors.
 */
export declare function computeColorDistance(color1: HexString, color2: HexString): number;
/**
 * Computes the contrast ratio between two hex colors using the
 * HCT color space.
 *
 * Returns a value between 1 and 21, where:
 * - 1:1 contrast ratio, no contrast
 * - 3:1 contrast ratio, AA large text
 * - 4.5:1 contrast ratio, AA small text / AAA large text
 * - 7:1 contrast ratio, AAA small text
 *
 * @param color1 - The first hex color.
 * @param color2 - The second hex color.
 * @returns The contrast ratio between the two colors.
 */
export declare function computeContrastRatio(color1: HexString, color2: HexString): number;
/**
 * Computes the contrast ratio between two tones using the
 * Y value from the L*a*b* color space.
 *
 * Returns a value between 1 and 21, where:
 * - 1:1 contrast ratio, no contrast
 * - 3:1 contrast ratio, AA large text
 * - 4.5:1 contrast ratio, AA small text / AAA large text
 * - 7:1 contrast ratio, AAA small text
 *
 * @param tone1 - The first tone.
 * @param tone2 - The second tone.
 * @returns The contrast ratio between the two tones.
 */
export declare function computeContrastRatioFromTone(tone1: number, tone2: number): number;