@electrovir/color
Version:
A wrapper for culori with an extremely simple API.
217 lines (216 loc) • 6.95 kB
TypeScript
import { type PartialWithUndefined } from '@augment-vir/common';
import { type RequireExactlyOne } from 'type-fest';
import { ColorFormatName, ColorSyntaxName, type ColorCoordsByFormat, type ColorValue, type HexColor } from './color-formats.js';
/**
* An update to an existing {@link Color} instance. Used in {@link Color.set}.
*
* @category Internal
*/
export type ColorUpdate = RequireExactlyOne<{
[]: PartialWithUndefined<Record<ColorCoordsByFormat[FormatName], number>>;
} & {
[]: HexColor;
[]: string;
}>;
/**
* The values of all supported color formats for a given {@link Color} instance. Accessed via
* `Color.allColors`.
*
* @category Internal
*/
export type AllColorsValues = ColorValue & {
hexString: HexColor;
[]: string;
names: string[];
};
/**
* The output of `Color.serialize()`.
*
* @category Internal
*/
export type SerializedColor = AllColorsValues & {
originalColorSyntax: ColorSyntaxName;
};
/**
* A `Color` class with state and the following features:
*
* - Color coordinates do not change when they become `'none'`, they stay at their previous value.
* This makes for a much smoother UI experience.
* - All relevant color spaces and formats are always set (no extra conversions necessary).
* - Matching CSS color names are tracked.
* - This class is exported correctly and the types aren't a mess.
*
* @category Color
*/
export declare class Color {
constructor(
/** Any valid CSS color string or an object of color coordinate values. */
initValue: string | Readonly<ColorUpdate>);
/** Checks if the input string can be converted into a color. */
static isValidColorString(this: void, value: string): boolean;
/** Checks, with a type guard, that a given input is a Color class instance. */
static isColor<T>(this: void, value: T): value is Extract<T, Readonly<Color>>;
/**
* Create a new {@link Color} instance by parsing the output of another instance's
* {@link Color.serialize} method.
*/
static deserialize(this: void, input: string): Color;
/** Get the distance from this Color class instance to the given CSS color string. */
getRgbDistance(distanceFrom: string): number;
/** Get the closest named CSS color to this Color class instance's current color. */
getClosestNamedColor(): string;
/**
* Converts the color class to a CSS string format in the color space and format that it was
* originally set with.
*/
toString(): string;
/** The color syntax the this color was set with. */
protected originalColorSyntax: ColorSyntaxName;
/** All current color values. These are updated whenever {@link Color.set} is called. */
protected readonly _allColors: {
names: string[];
name: string;
hexString: HexColor;
hex: {
r: number;
g: number;
b: number;
};
rgb: {
r: number;
g: number;
b: number;
};
hsl: {
h: number;
s: number;
l: number;
};
hwb: {
h: number;
w: number;
b: number;
};
lab: {
l: number;
a: number;
b: number;
};
lch: {
l: number;
c: number;
h: number;
};
oklab: {
l: number;
a: number;
b: number;
};
oklch: {
l: number;
c: number;
h: number;
};
};
/** Create a new {@link Color} instance that matches this one exactly. */
clone(): Color;
/**
* Update the color to match the given string.
*
* @throws Error if `cssColorString` is not able to be parsed.
*/
protected setByString(cssColorString: string): void;
/**
* Update the current color by setting a whole new color, a single coordinate in a single color
* format, or multiple coordinates in a single color format. This mutates the current
* {@link Color} instance.
*/
set(newValue: Readonly<ColorUpdate> | string): void;
/**
* Update all internally stored color format values ({@link Color.allColors}) from the updated
* internal color object.
*/
protected pullFromInternalColor(): void;
/**
* Create a string that can be serialized into a new {@link Color} instance which will exactly
* match the current {@link Color} instance.
*/
serialize(): string;
/** This individual color expressed in all the supported color formats. */
get allColors(): AllColorsValues;
/**
* Converts the values for each supported color format into a padded string for easy display
* purposes.
*
* @see `.toCss()`
*/
toFormattedStrings(): Record<ColorSyntaxName | 'names', string>;
/**
* Converts the values for each supported color format in a CSS string that can be directly used
* in any modern CSS code.
*
* @see `.toFormattedStrings()`
*/
toCss(): Record<ColorSyntaxName, string>;
/**
* The current color expressed as hardcoded CSS color keywords. If no CSS color keywords match
* the current color, this array will be empty.
*/
get names(): string[];
/**
* The current color expressed as a single CSS color name string. If there is no color name that
* matches the current color, this will be an empty string.
*/
get name(): string;
/** The current color expressed as an RGB hex string. */
get hexString(): `#${string}`;
/** The current color expressed as an RGB hex coordinates. */
get hex(): {
r: number;
g: number;
b: number;
};
/** The current color expressed as its RGB coordinate values. */
get rgb(): {
r: number;
g: number;
b: number;
};
/** The current color expressed as its HSL coordinate values. */
get hsl(): {
h: number;
s: number;
l: number;
};
/** The current color expressed as its HWB coordinate values. */
get hwb(): {
b: number;
h: number;
w: number;
};
/** The current color expressed as its LAB coordinate values. */
get lab(): {
b: number;
l: number;
a: number;
};
/** The current color expressed as its LCH coordinate values. */
get lch(): {
h: number;
l: number;
c: number;
};
/** The current color expressed as its Oklab coordinate values. */
get oklab(): {
b: number;
l: number;
a: number;
};
/** The current color expressed as its Oklch coordinate values. */
get oklch(): {
h: number;
l: number;
c: number;
};
}