precise-colors 0.9.7 → 0.9.8

package/dist/index.d.cts

@@ -1,133 +1,423 @@
+/**
+ * CMYK color model (Cyan, Magenta, Yellow, Key/Black).
+ * @property {number} c - Cyan `[0..100]`
+ * @property {number} m - Magenta `[0..100]`
+ * @property {number} y - Yellow `[0..100]`
+ * @property {number} k - Key/Black `[0..100]`
+ * @see {@link https://en.wikipedia.org/wiki/CMYK_color_model|Wikipedia}
+ */
 interface Cmyk {
-    /** [0..100] */
+    /** Cyan `[0..100]` */
     readonly c: number;
-    /** [0..100] */
+    /** Magenta `[0..100]` */
     readonly m: number;
-    /** [0..100] */
+    /** Yellow `[0..100]` */
     readonly y: number;
-    /** [0..100] */
+    /** Key/Black `[0..100]` */
     readonly k: number;
 }
+/**
+ * Apple 16-bit RGB color.
+ * @property {number} r16 - Red `[0..65535]`
+ * @property {number} g16 - Green `[0..65535]`
+ * @property {number} b16 - Blue `[0..65535]`
+ * @see {@link https://developer.apple.com/library/archive/documentation/LanguagesUtilities/Conceptual/MacAutomationScriptingGuide/ConvertRGBtoHTMLColor.html|Apple RGB}
+ */
 interface Apple {
+    /** Red `[0..65535]` */
     readonly r16: number;
+    /** Green `[0..65535]` */
     readonly g16: number;
+    /** Blue `[0..65535]` */
     readonly b16: number;
 }
+/**
+ * sRGB color model (8-bit per channel).
+ * @property {number} r - Red `[0..255]`
+ * @property {number} g - Green `[0..255]`
+ * @property {number} b - Blue `[0..255]`
+ * @see {@link https://www.color.org/srgb.pdf|ICC sRGB Specification}
+ */
 interface Rgb {
-    /** [0..255] */
+    /** Red `[0..255]` */
     readonly r: number;
-    /** [0..255] */
+    /** Green `[0..255]` */
     readonly g: number;
-    /** [0..255] */
+    /** Blue `[0..255]` */
     readonly b: number;
 }
+/**
+ * HSL cylindrical color model (Hue, Saturation, Lightness).
+ * @property {number} h - Hue `[0..360]`
+ * @property {number} s - Saturation `[0..100]`
+ * @property {number} l - Lightness `[0..100]`
+ * @see {@link https://www.w3.org/TR/css-color-4/#the-hsl-notation|W3C CSS Color 4}
+ */
 interface Hsl {
+    /** Hue angle `[0..360]` */
     readonly h: number;
+    /** Saturation `[0..100]` */
     readonly s: number;
+    /** Lightness `[0..100]` */
     readonly l: number;
 }
+/**
+ * HSV/HSB cylindrical color model (Hue, Saturation, Value/Brightness).
+ * @property {number} h - Hue `[0..360]`
+ * @property {number} s - Saturation `[0..100]`
+ * @property {number} v - Value `[0..100]`
+ * @see {@link https://en.wikipedia.org/wiki/HSL_and_HSV|Wikipedia}
+ */
 interface Hsv {
+    /** Hue angle `[0..360]` */
     readonly h: number;
+    /** Saturation `[0..100]` */
     readonly s: number;
+    /** Value/Brightness `[0..100]` */
     readonly v: number;
 }
+/**
+ * HCG color model (Hue, Chroma, Grayness).
+ * Derived from the Munsell color system.
+ * @property {number} h - Hue `[0..360]`
+ * @property {number} c - Chroma `[0..100]`
+ * @property {number} g - Grayness `[0..100]`
+ * @see {@link https://github.com/d3/d3-hcg|d3-hcg}
+ */
 interface Hcg {
+    /** Hue angle `[0..360]` */
     readonly h: number;
+    /** Chroma `[0..100]` */
     readonly c: number;
+    /** Grayness `[0..100]` */
     readonly g: number;
 }
+/**
+ * HWB color model (Hue, Whiteness, Blackness).
+ * @property {number} h - Hue `[0..360]`
+ * @property {number} w - Whiteness `[0..100]`
+ * @property {number} b - Blackness `[0..100]`
+ * @see {@link https://www.w3.org/TR/css-color-4/#the-hwb-notation|W3C CSS Color 4}
+ */
 interface Hwb {
-    /** Hue [0..360] */
+    /** Hue angle `[0..360]` */
     readonly h: number;
-    /** Whiteness [0..100] */
+    /** Whiteness `[0..100]` */
     readonly w: number;
-    /** Blackness [0..100] */
+    /** Blackness `[0..100]` */
     readonly b: number;
 }
+/**
+ * CIE L*a*b* perceptual color space (1976).
+ * a* and b* are theoretically unbounded but clamped to `[-128..127]` for 8-bit storage.
+ * @property {number} l - Lightness `[0..100]`
+ * @property {number} a - Green-Red axis `[-128..127]`
+ * @property {number} b - Blue-Yellow axis `[-128..127]`
+ * @see {@link https://en.wikipedia.org/wiki/CIELAB_color_space|Wikipedia}
+ * @see {@link https://www.w3.org/TR/css-color-4/#lab-colors|W3C CSS Color 4}
+ */
 interface Lab {
+    /** Lightness `[0..100]` */
     readonly l: number;
+    /** Green (-) to Red (+) axis. Clamped `[-128..127]`, theoretical `~[-430..+172]` */
     readonly a: number;
+    /** Blue (-) to Yellow (+) axis. Clamped `[-128..127]`, theoretically unbounded */
     readonly b: number;
 }
+/**
+ * CIE XYZ tristimulus color space with D65 illuminant.
+ * @property {number} x - X tristimulus `[0..95.047]`
+ * @property {number} y - Y luminance `[0..100]`
+ * @property {number} z - Z tristimulus `[0..108.883]`
+ * @see {@link https://en.wikipedia.org/wiki/CIE_1931_color_space|Wikipedia CIE 1931}
+ * @see {@link https://en.wikipedia.org/wiki/Standard_illuminant#Illuminant_series_D|D65 Illuminant}
+ */
 interface Xyz {
+    /** X tristimulus `[0..95.047]` for D65 white */
     readonly x: number;
+    /** Y tristimulus (luminance) `[0..100]` */
     readonly y: number;
+    /** Z tristimulus `[0..108.883]` for D65 white */
     readonly z: number;
 }
+/**
+ * XYZ values from Lab conversion (named Lyz to avoid confusion).
+ * Uses D65 illuminant reference white.
+ * @property {number} l - X tristimulus `[0..95.047]`
+ * @property {number} y - Y luminance `[0..100]`
+ * @property {number} z - Z tristimulus `[0..108.883]`
+ * @see {@link https://en.wikipedia.org/wiki/Standard_illuminant#Illuminant_series_D|D65 Illuminant}
+ */
 interface Lyz {
+    /** X tristimulus `[0..95.047]` for D65 */
     readonly l: number;
+    /** Y tristimulus `[0..100]` */
     readonly y: number;
+    /** Z tristimulus `[0..108.883]` for D65 */
     readonly z: number;
 }
+/**
+ * CIE LCH cylindrical color space (Lightness, Chroma, Hue).
+ * Polar representation of L*a*b*.
+ * @property {number} l - Lightness `[0..100]`
+ * @property {number} c - Chroma `[0..~230]`
+ * @property {number} h - Hue `[0..360]`
+ * @see {@link https://en.wikipedia.org/wiki/CIELAB_color_space#Cylindrical_model|Wikipedia}
+ * @see {@link https://www.w3.org/TR/css-color-4/#lch-colors|W3C CSS Color 4}
+ */
 interface Lch {
+    /** Lightness `[0..100]` */
     readonly l: number;
+    /** Chroma `[0..~230]`. Theoretically unbounded, sRGB max ~131 */
     readonly c: number;
+    /** Hue angle `[0..360]` */
     readonly h: number;
 }
-/** rounds number to amount of places after `.` */
+/**
+ * Rounds a number to specified decimal places.
+ * Uses exponential notation to avoid floating-point errors
+ * (e.g., `1.005 * 100 = 100.49999...` but `roundTo(1.005, 2) = 1.01`).
+ * @param num - Number to round
+ * @param places - Decimal places `[0..]`
+ * @returns Rounded number
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toFixed|Number.toFixed} for string output
+ */
 declare function roundTo(num: number, places: number): number;
+/**
+ * Modulo operation that always returns positive result.
+ * @param x - Dividend
+ * @param n - Divisor
+ * @returns `x mod n`, always positive
+ */
 declare function modulo(x: number, n: number): number;
 /**
- * rgb2css converts {@link Rgb} to a string for css. Calls `Math.round` for each of
- * the Rgb fields.
- * @param {Rbg} rgb - [0..255].
- * @returns {string} `"rgb(r,g,b)"` representation of passed {@link Rgb} instance.
+ * Converts {@link Rgb} to CSS rgb() string.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns CSS string `"rgb(r,g,b)"` (rounded)
  */
 declare function rgb2css(rgb: Rgb): string;
 /**
- * rgb2str converts {@link Rgb} to a rounded `"0..255,0.255,0.255"` string.
- * @param {Rgb} rgb
- * @returns {string} example: `"0,127,255"`
+ * Converts {@link Rgb} to comma-separated string.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns String `"r,g,b"` (rounded)
  */
 declare function rgb2str(rgb: Rgb): string;
 /**
- * Converts {@link Rgb} and `alpha` to a string for css. Calls `Math.round` for each of
- * the Rgb fields. Rounds `alpha` to max 2 places after `.`.
- * @param {Rbg} rgb - [0..255].
- * @param {number} alpha [0..1]
- * @returns {string} `"rgb(r,g,b,a)"` representation of passed  {@link Rgb} instance and `alpha`.
+ * Converts {@link Rgb} and alpha to CSS rgba() string.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @param alpha - Alpha `[0..1]`
+ * @returns CSS string `"rgba(r,g,b,a)"` (rounded)
  */
 declare function rgba2css(rgb: Rgb, alpha: number): string;
-/** returns `hsl(h,s,l)` expression */
+/**
+ * Converts {@link Hsl} to CSS hsl() string.
+ * @param hsl - {@link Hsl} color, h `[0..360]`, s/l `[0..100]`
+ * @returns CSS string `"hsl(hdeg,s%,l%)"` (rounded to 2 decimals)
+ */
 declare function hsl2css(hsl: Hsl): string;
-/** returns `hwb(h,w,b)` expression */
+/**
+ * Converts {@link Hwb} to CSS hwb() string.
+ * @param hwb - {@link Hwb} color, h `[0..360]`, w/b `[0..100]`
+ * @returns CSS string `"hwb(hdeg,w%,b%)"` (rounded to 2 decimals)
+ */
 declare function hwb2css(hwb: Hwb): string;
-/** rgb expects [0..255] for each field */
+/**
+ * Converts {@link Rgb} to 6-digit hex string (without #).
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns Hex string `"rrggbb"` (rounded)
+ */
 declare function rgb2hex(rgb: Rgb): string;
-/** gray expects [0..100] */
+/**
+ * Converts gray value to 6-digit hex string.
+ * @param gray - Gray level `[0..100]`
+ * @returns Hex string `"gggggg"` (rounded)
+ */
 declare function gray2hex(gray: number): string;
+/**
+ * Parses hex string to {@link Rgb}.
+ * @param input - Hex string (6 digits, without #)
+ * @returns {@link Rgb} color, r/g/b `[0..255]`
+ */
 declare function hex2rgb(input: string): Rgb;
-/** expects h [0..360], s [0..100], l [0..100]. Returns rgb[0..255], doesn't perform Math.round on the result. */
+/**
+ * Converts {@link Hsl} to {@link Rgb}.
+ * @param hsl - {@link Hsl} color, h `[0..360]`, s/l `[0..100]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]` (not rounded)
+ */
 declare function hsl2rgb(hsl: Hsl): Rgb;
-/** expects h [0..360], s [0..100], l [0..100]. Returns rgb[0..255], doesn't perform Math.round on the result. */
+/**
+ * Converts {@link Hsl} to {@link Hsv}.
+ * @param hsl - {@link Hsl} color, h `[0..360]`, s/l `[0..100]`
+ * @returns {@link Hsv} color, h `[0..360]`, s/v `[0..100]`
+ */
 declare function hsl2hsv(hsl: Hsl): Hsv;
+/**
+ * Converts {@link Hsl} to {@link Hcg}.
+ * @param hsl - {@link Hsl} color, h `[0..360]`, s/l `[0..100]`
+ * @returns {@link Hcg} color, h `[0..360]`, c/g `[0..100]`
+ */
 declare function hsl2hcg(hsl: Hsl): Hcg;
+/**
+ * Converts {@link Hsv} to {@link Rgb}.
+ * @param hsv - {@link Hsv} color, h `[0..360]`, s/v `[0..100]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]` (not rounded)
+ */
 declare function hsv2rgb(hsv: Hsv): Rgb;
+/**
+ * Converts {@link Hsv} to {@link Hsl}.
+ * @param hsv - {@link Hsv} color, h `[0..360]`, s/v `[0..100]`
+ * @returns {@link Hsl} color, h `[0..360]`, s/l `[0..100]`
+ */
 declare function hsv2hsl(hsv: Hsv): Hsl;
+/**
+ * Converts {@link Hsv} to {@link Hcg}.
+ * @param hsv - {@link Hsv} color, h `[0..360]`, s/v `[0..100]`
+ * @returns {@link Hcg} color, h `[0..360]`, c/g `[0..100]`
+ */
 declare function hsv2hcg(hsv: Hsv): Hcg;
+/**
+ * Converts {@link Apple} 16-bit RGB to 8-bit {@link Rgb}.
+ * @param rgb16 - {@link Apple} color, r16/g16/b16 `[0..65535]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]`
+ */
 declare function apple2rgb(rgb16: Apple): Rgb;
+/**
+ * Converts {@link Cmyk} to {@link Rgb}.
+ * @param cmyk - {@link Cmyk} color, c/m/y/k `[0..100]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]`
+ */
 declare function cmyk2rgb(cmyk: Cmyk): Rgb;
+/**
+ * Converts {@link Rgb} to {@link Cmyk}.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns {@link Cmyk} color, c/m/y/k `[0..100]`
+ */
 declare function rgb2cmyk(rgb: Rgb): Cmyk;
+/**
+ * Converts {@link Rgb} to {@link Hsl}.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns {@link Hsl} color, h `[0..360]`, s/l `[0..100]`
+ */
 declare function rgb2hsl(rgb: Rgb): Hsl;
+/**
+ * Converts {@link Rgb} to {@link Hwb}.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns {@link Hwb} color, h `[0..360]`, w/b `[0..100]`
+ */
 declare function rgb2hwb(rgb: Rgb): Hwb;
+/**
+ * Converts {@link Hwb} to {@link Rgb}.
+ * @param hwb - {@link Hwb} color, h `[0..360]`, w/b `[0..100]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]` (not rounded)
+ */
 declare function hwb2rgb(hwb: Hwb): Rgb;
+/**
+ * Converts {@link Hwb} to {@link Hcg}.
+ * @param hwb - {@link Hwb} color, h `[0..360]`, w/b `[0..100]`
+ * @returns {@link Hcg} color, h `[0..360]`, c/g `[0..100]`
+ */
 declare function hwb2hcg(hwb: Hwb): Hcg;
+/**
+ * Converts {@link Hcg} to {@link Rgb}.
+ * @param hcg - {@link Hcg} color, h `[0..360]`, c/g `[0..100]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]` (not rounded)
+ */
 declare function hcg2rgb(hcg: Hcg): Rgb;
+/**
+ * Converts {@link Hcg} to {@link Hsv}.
+ * @param hcg - {@link Hcg} color, h `[0..360]`, c/g `[0..100]`
+ * @returns {@link Hsv} color, h `[0..360]`, s/v `[0..100]`
+ */
 declare function hcg2hsv(hcg: Hcg): Hsv;
+/**
+ * Converts {@link Hcg} to {@link Hsl}.
+ * @param hcg - {@link Hcg} color, h `[0..360]`, c/g `[0..100]`
+ * @returns {@link Hsl} color, h `[0..360]`, s/l `[0..100]`
+ */
 declare function hcg2hsl(hcg: Hcg): Hsl;
+/**
+ * Converts {@link Hcg} to {@link Hwb}.
+ * @param hcg - {@link Hcg} color, h `[0..360]`, c/g `[0..100]`
+ * @returns {@link Hwb} color, h `[0..360]`, w/b `[0..100]`
+ */
 declare function hcg2hwb(hcg: Hcg): Hwb;
+/**
+ * Converts gray to {@link Rgb}.
+ * @param gray - Gray level `[0..100]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]`
+ */
 declare function gray2rgb(gray: number): Rgb;
+/**
+ * Converts gray to {@link Hsl}.
+ * @param gray - Gray level `[0..100]`
+ * @returns {@link Hsl} color, h=0, s=0, l=gray
+ */
 declare function gray2hsl(gray: number): Hsl;
+/**
+ * Converts gray to {@link Hsv}.
+ * @param gray - Gray level `[0..100]`
+ * @returns {@link Hsv} color, h=0, s=0, v=gray
+ */
 declare function gray2hsv(gray: number): Hsv;
+/**
+ * Converts gray to {@link Hwb}.
+ * @param gray - Gray level `[0..100]`
+ * @returns {@link Hwb} color, h=0, w=gray, b=100-gray
+ */
 declare function gray2hwb(gray: number): Hwb;
+/**
+ * Converts gray to {@link Cmyk}.
+ * @param gray - Gray level `[0..100]`
+ * @returns {@link Cmyk} color, c=0, m=0, y=0, k=gray
+ */
 declare function gray2cmyk(gray: number): Cmyk;
+/**
+ * Converts gray to {@link Lab}.
+ * @param gray - Gray level `[0..100]`
+ * @returns {@link Lab} color, l=gray, a=0, b=0
+ */
 declare function gray2lab(gray: number): Lab;
+/**
+ * Converts {@link Rgb} to {@link Lab}.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns {@link Lab} color, l `[0..100]`, a/b `[-128..127]`
+ */
 declare function rgb2lab(rgb: Rgb): Lab;
+/**
+ * Converts {@link Lab} to {@link Lyz} (XYZ values).
+ * @param lab - {@link Lab} color, l `[0..100]`, a/b `[-128..127]`
+ * @returns {@link Lyz} color, l `[0..95.047]`, y `[0..100]`, z `[0..108.883]`
+ */
 declare function lab2lyz(lab: Lab): Lyz;
+/**
+ * Converts {@link Lab} to {@link Lch}.
+ * @param lab - {@link Lab} color, l `[0..100]`, a/b `[-128..127]`
+ * @returns {@link Lch} color, l `[0..100]`, c `[0..~230]`, h `[0..360]`
+ */
 declare function lab2lch(lab: Lab): Lch;
+/**
+ * Converts {@link Lch} to {@link Lab}.
+ * @param lch - {@link Lch} color, l `[0..100]`, c `[0..~230]`, h `[0..360]`
+ * @returns {@link Lab} color, l `[0..100]`, a/b `[-128..127]`
+ */
 declare function lch2lab(lch: Lch): Lab;
+/**
+ * Converts {@link Xyz} to {@link Rgb}.
+ * @param xyz - {@link Xyz} color, x `[0..95.047]`, y `[0..100]`, z `[0..108.883]`
+ * @returns {@link Rgb} color, r/g/b `[0..255]`
+ */
 declare function xyz2rgb(xyz: Xyz): Rgb;
+/**
+ * Converts {@link Xyz} to {@link Lab}.
+ * @param xyz - {@link Xyz} color, x `[0..95.047]`, y `[0..100]`, z `[0..108.883]`
+ * @returns {@link Lab} color, l `[0..100]`, a/b `[-128..127]`
+ */
 declare function xyz2lab(xyz: Xyz): Lab;
+/**
+ * Converts {@link Rgb} to {@link Xyz}.
+ * @param rgb - {@link Rgb} color, r/g/b `[0..255]`
+ * @returns {@link Xyz} color, x `[0..95.047]`, y `[0..100]`, z `[0..108.883]`
+ */
 declare function rgb2xyz(rgb: Rgb): Xyz;
 
 export { type Apple, type Cmyk, type Hcg, type Hsl, type Hsv, type Hwb, type Lab, type Lch, type Lyz, type Rgb, type Xyz, apple2rgb, cmyk2rgb, gray2cmyk, gray2hex, gray2hsl, gray2hsv, gray2hwb, gray2lab, gray2rgb, hcg2hsl, hcg2hsv, hcg2hwb, hcg2rgb, hex2rgb, hsl2css, hsl2hcg, hsl2hsv, hsl2rgb, hsv2hcg, hsv2hsl, hsv2rgb, hwb2css, hwb2hcg, hwb2rgb, lab2lch, lab2lyz, lch2lab, modulo, rgb2cmyk, rgb2css, rgb2hex, rgb2hsl, rgb2hwb, rgb2lab, rgb2str, rgb2xyz, rgba2css, roundTo, xyz2lab, xyz2rgb };