@texel/color - npm Package Compare versions

Comparing version 1.1.4 to 1.1.5

.jsdoc.json

+{
+  "source": {
+    "include": ["src", "src/spaces"]
+  },
+  "sourceType": "module",
+  "tags": {
+    "allowUnknownTags": ["category", "subcategory"]
+  },
+  "plugins": ["node_modules/better-docs/category"]
+}

DOC.md

+`@texel/color` is a minimal and modern color library for JavaScript. Especially useful for real-time applications, generative art, and graphics on the web.
+
+## Source Code
+
+The source code is on GitHub:
+
+[https://github.com/texel-org/color](https://github.com/texel-org/color)
+
+## Docs
+
+The documentation is held here:
+
+[https://texel-org.github.io/color](https://texel-org.github.io/color)
+
+## Usage
+
+For installation and usage, see the [README.md page](https://github.com/texel-org/color/) on the GitHub repository.

types/types.d.ts

+/**
+ * A 3x3 matrix represented as an array of arrays.
+ * @example
+ * const matrix = [
+ *   [a, b, c],
+ *   [d, e, f],
+ *   [g, h, i]
+ * ];
+ */
+declare type Matrix3x3 = number[][];
+
+/**
+ * A n-dimensional vector represented as an array of numbers, typically in 3D (X, Y, Z).
+ * @example
+ * const vec = [ x, y, z ];
+ */
+declare type Vector = number[];
+
+/**
+ * @property id - the unique identifier for this color space in lowercase
+ * @property [toXYZ_M] - optional matrix to convert this color directly to XYZ D65
+ * @property [fromXYZ_M] - optional matrix to convert XYZ D65 to this color space
+ * @property [toLMS_M] - optional matrix to convert this color space to OKLab's LMS intermediary form
+ * @property [fromLMS_M] - optional matrix to convert OKLab's LMS intermediary form to this color space
+ * @property [adapt] - optional chromatic adaptation matrices
+ * @property [base] - an optional base color space that this space is derived from
+ * @property [toBase] - if a base color space exists, this maps the color to the base space form (e.g. gamma to the linear base space)
+ * @property [fromBase] - if a base color space exists, this maps the color from the base space form (e.g. the linear base space to the gamma space)
+ */
+declare type ColorSpace = {
+  id: string;
+  toXYZ_M?: Matrix3x3;
+  fromXYZ_M?: Matrix3x3;
+  toLMS_M?: Matrix3x3;
+  fromLMS_M?: Matrix3x3;
+  adapt?: any;
+  base?: ColorSpace;
+  toBase?: (...params: any[]) => any;
+  fromBase?: (...params: any[]) => any;
+};
+
+/**
+ * @property space - the color space associated with this color gamut
+ */
+declare type ColorGamut = {
+  space: ColorSpace;
+};
+
+/**
+ * Converts OKLab color to another color space.
+ * @param OKLab - The OKLab color.
+ * @param LMS_to_output - The transformation matrix from LMS to the output color space.
+ * @param [out = vec3()] - The output vector.
+ * @returns The transformed color.
+ */
+declare function OKLab_to(
+  OKLab: Vector,
+  LMS_to_output: Matrix3x3,
+  out?: Vector
+): Vector;
+
+/**
+ * Converts a color from another color space to OKLab.
+ * @param input - The input color.
+ * @param input_to_LMS - The transformation matrix from the input color space to LMS.
+ * @param [out = vec3()] - The output vector.
+ * @returns The transformed color.
+ */
+declare function OKLab_from(
+  input: Vector,
+  input_to_LMS: Matrix3x3,
+  out?: Vector
+): Vector;
+
+/**
+ * Transforms a color vector by the specified 3x3 transformation matrix.
+ * @param input - The input color.
+ * @param matrix - The transformation matrix.
+ * @param [out = vec3()] - The output vector.
+ * @returns The transformed color.
+ */
+declare function transform(
+  input: Vector,
+  matrix: Matrix3x3,
+  out?: Vector
+): Vector;
+
+/**
+ * Serializes a color to a CSS color string.
+ * @param input - The input color.
+ * @param inputSpace - The input color space.
+ * @param [outputSpace = inputSpace] - The output color space.
+ * @returns The serialized color string.
+ */
+declare function serialize(
+  input: Vector,
+  inputSpace: ColorSpace,
+  outputSpace?: ColorSpace
+): string;
+
+/**
+ * Deserializes a color string to an object with <code>id</code> (color space string) and <code>coords</code> (the vector, in 3 or 4 dimensions).
+ * Note this does not return a <code>ColorSpace</code> object; you may want to use the example code below to map the string ID to a <code>ColorSpace</code>, but this will increase the size of your final bundle as it references all spaces.
+ * @example
+ * import { listColorSpaces, deserialize } from "@texel/color";
+ *
+ * const { id, coords } = deserialize(str);
+ * // now find the actual color space object
+ * const space = listColorSpaces().find((f) => id === f.id);
+ * console.log(space, coords);
+ * @param input - The color string to deserialize.
+ * @returns The deserialized color object.
+ */
+declare function deserialize(input: string): any;
+
+/**
+ * Parses a color string and converts it to the target color space.
+ * @param input - The color string to parse.
+ * @param targetSpace - The target color space.
+ * @param [out = vec3()] - The output vector.
+ * @returns The parsed and converted color.
+ */
+declare function parse(
+  input: string,
+  targetSpace: ColorSpace,
+  out?: Vector
+): Vector;
+
+/**
+ * Converts a color from one color space to another.
+ * @param input - The input color.
+ * @param fromSpace - The source color space.
+ * @param toSpace - The target color space.
+ * @param [out = vec3()] - The output vector.
+ * @returns The converted color.
+ */
+declare function convert(
+  input: Vector,
+  fromSpace: ColorSpace,
+  toSpace: ColorSpace,
+  out?: Vector
+): Vector;
+
+/**
+ * Calculates the DeltaEOK (color difference) between two OKLab colors.
+ * @param oklab1 - The first OKLab color.
+ * @param oklab2 - The second OKLab color.
+ * @returns The delta E value.
+ */
+declare function deltaEOK(oklab1: Vector, oklab2: Vector): number;
+
+/**
+ * A function that maps an OKLCH color to a lightness value.
+ * @param oklch - The input OKLCH color
+ * @param cusp - A 2D cusp point in the form [L, C]
+ */
+declare type GamutMapMethod = (oklch: Vector, cusp: number[]) => void;
+
+/**
+ * A {@link GamutMapMethod} that maintains the color's lightness.
+ */
+declare const MapToL: GamutMapMethod;
+
+/**
+ * A {@link GamutMapMethod} that maps towards middle gray (L = 0.5).
+ */
+declare const MapToGray: GamutMapMethod;
+
+/**
+ * A {@link GamutMapMethod} that maps towards the lightness of the current hue's cusp.
+ */
+declare const MapToCuspL: GamutMapMethod;
+
+/**
+ * A {@link GamutMapMethod} that adaptively maps towards gray.
+ */
+declare const MapToAdaptiveGray: GamutMapMethod;
+
+/**
+ * A {@link GamutMapMethod} that adaptively maps towards the cusp's lightness.
+ */
+declare const MapToAdaptiveCuspL: GamutMapMethod;
+
+/**
+ * Computes the maximum saturation (S = C/L) possible for a given hue that fits within
+ * the RGB gamut, using the given coefficients.
+ * @param a - The normalized a component of the hue.
+ * @param b - The normalized b component of the hue.
+ * @param lmsToRgb - The LMS to RGB conversion matrix.
+ * @param okCoeff - The OKLab coefficients.
+ * @returns The maximum saturation.
+ */
+declare function computeMaxSaturationOKLC(
+  a: number,
+  b: number,
+  lmsToRgb: number[][],
+  okCoeff: number[][][]
+): number;
+
+/**
+ * Retrieves the LMS to RGB conversion matrix from the given gamut.
+ * @param gamut - The gamut object.
+ * @returns The LMS to RGB conversion matrix.
+ */
+declare function getGamutLMStoRGB(gamut: ColorGamut): Matrix3x3;
+
+/**
+ * Finds the cusp of the OKLCH color space for a given hue.
+ * @param a - The normalized a component of the hue.
+ * @param b - The normalized b component of the hue.
+ * @param gamut - The gamut object.
+ * @param [out = [0, 0]] - The output array to store the cusp values.
+ * @returns The cusp values [L, C].
+ */
+declare function findCuspOKLCH(
+  a: number,
+  b: number,
+  gamut: ColorGamut,
+  out?: number[]
+): number[];
+
+/**
+ * Applies fast approximate gamut mapping in OKLab space on the given OKLCH input color,
+ * using the specified gamut and converting to the target color space.
+ * @param oklch - The input OKLCH color that you wish to gamut map.
+ * @param [gamut = sRGBGamut] - The gamut object.
+ * @param [targetSpace = gamut.space] - The target color space.
+ * @param [out = vec3()] - The output array to store the mapped color.
+ * @param [mapping = MapToCuspL] - The gamut mapping function.
+ * @param [cusp] - Optional, you can provide the cusp values [L, C] to avoid re-computing them.
+ * @returns The mapped color in the target color space.
+ */
+declare function gamutMapOKLCH(
+  oklch: Vector,
+  gamut?: ColorGamut,
+  targetSpace?: ColorSpace,
+  out?: Vector,
+  mapping?: GamutMapMethod,
+  cusp?: Vector
+): Vector;
+
+/**
+ * Converts OKHSL color to OKLab color.
+ * @param hsl - The OKHSL color as an array [h, s, l].
+ * @param [gamut = sRGBGamut] - The color gamut.
+ * @param [out = vec3()] - The output array to store the OKLab color.
+ * @returns The OKLab color as an array [L, a, b].
+ */
+declare function OKHSLToOKLab(
+  hsl: Vector,
+  gamut?: ColorGamut,
+  out?: Vector
+): Vector;
+
+/**
+ * Converts OKLab color to OKHSL color.
+ * @param lab - The OKLab color as an array [L, a, b].
+ * @param [gamut = sRGBGamut] - The color gamut.
+ * @param [out = vec3()] - The output array to store the OKHSL color.
+ * @returns The OKHSL color as an array [h, s, l].
+ */
+declare function OKLabToOKHSL(
+  lab: Vector,
+  gamut?: ColorGamut,
+  out?: Vector
+): Vector;
+
+/**
+ * Converts OKHSV color to OKLab color.
+ * @param hsv - The OKHSV color as an array [h, s, v].
+ * @param [gamut = sRGBGamut] - The color gamut.
+ * @param [out = vec3()] - The output array to store the OKLab color.
+ * @returns The OKLab color as an array [L, a, b].
+ */
+declare function OKHSVToOKLab(
+  hsv: Vector,
+  gamut?: ColorGamut,
+  out?: Vector
+): Vector;
+
+/**
+ * Converts OKLab color to OKHSV color.
+ * @param lab - The OKLab color as an array [L, a, b].
+ * @param [gamut = sRGBGamut] - The color gamut.
+ * @param [out = vec3()] - The output array to store the OKHSV color.
+ * @returns The OKHSV color as an array [h, s, v].
+ */
+declare function OKLabToOKHSV(
+  lab: Vector,
+  gamut?: ColorGamut,
+  out?: Vector
+): Vector;
+
+/**
+ * Returns a list of color spaces.
+ * @returns An array of color space objects.
+ */
+declare function listColorSpaces(): ColorSpace[];
+
+/**
+ * Returns a list of color gamuts.
+ * @returns An array of color gamut objects.
+ */
+declare function listColorGamuts(): ColorGamut[];
+
+/**
+ * Clamps a value between a minimum and maximum value.
+ * @param value - The value to clamp.
+ * @param min - The minimum value.
+ * @param max - The maximum value.
+ * @returns The clamped value.
+ */
+declare function clamp(value: number, min: number, max: number): number;
+
+/**
+ * Linearly interpolates between two values.
+ * @param min - The start value.
+ * @param max - The end value.
+ * @param t - The interpolation factor between 0 and 1.
+ * @returns The interpolated value.
+ */
+declare function lerp(min: number, max: number, t: number): number;
+
+/**
+ * Converts degrees to radians.
+ * @param n - The angle in degrees.
+ * @returns The angle in radians.
+ */
+declare function degToRad(n: number): number;
+
+/**
+ * Converts radians to degrees.
+ * @param n - The angle in radians.
+ * @returns The angle in degrees.
+ */
+declare function radToDeg(n: number): number;
+
+/**
+ * Constrains an angle to the range [0, 360).
+ * @param angle - The angle in degrees.
+ * @returns The constrained angle.
+ */
+declare function constrainAngle(angle: number): number;
+
+/**
+ * Converts a hex color string to an RGB array.
+ * @param str - The hex color string.
+ * @param [out = vec3()] - The output array.
+ * @returns The RGB array.
+ */
+declare function hexToRGB(str: string, out?: Vector): Vector;
+
+/**
+ * Converts an RGB array to a hex color string.
+ * @param rgb - The RGB array.
+ * @returns The hex color string.
+ */
+declare function RGBToHex(rgb: Vector): string;
+
+declare function RGBtoHex(): void;
+
+/**
+ * Checks if an RGB color is within the gamut.
+ * @param lrgb - The linear RGB array.
+ * @param [ep = GAMUT_EPSILON] - The epsilon value for comparison.
+ * @returns True if the color is within the gamut, false otherwise.
+ */
+declare function isRGBInGamut(lrgb: Vector, ep?: number): boolean;
+
+/**
+ * Clamps an RGB array to the range [0, 1].
+ * @param rgb - The RGB array.
+ * @param [out = vec3()] - The output array.
+ * @returns The clamped RGB array.
+ */
+declare function clampedRGB(rgb: Vector, out?: Vector): Vector;
+
+/**
+ * Converts xyY color space to XYZ color space.
+ * @param arg - The xyY array.
+ * @param [out = vec3()] - The output array.
+ * @returns The XYZ array.
+ */
+declare function xyY_to_XYZ(arg: Vector, out?: Vector): Vector;
+
+/**
+ * Converts XYZ color space to xyY color space.
+ * @param arg - The XYZ array.
+ * @param [out = vec3()] - The output array.
+ * @returns The xyY array.
+ */
+declare function XYZ_to_xyY(arg: Vector, out?: Vector): Vector;
+
+/**
+ * Converts a float value to a byte value.
+ * @param n - The float value.
+ * @returns The byte value.
+ */
+declare function floatToByte(n: number): number;
+
+/**
+ * Creates a new vec3 array.
+ * @returns The vec3 array.
+ */
+declare function vec3(): Vector;
+
+/**
+ * Calculates the delta angle between two angles.
+ * @param a0 - The first angle in degrees.
+ * @param a1 - The second angle in degrees.
+ * @returns The delta angle in degrees.
+ */
+declare function deltaAngle(a0: number, a1: number): number;
+
+/**
+ * Linearly interpolates between two angles.
+ * @param a0 - The start angle in degrees.
+ * @param a1 - The end angle in degrees.
+ * @param t - The interpolation factor between 0 and 1.
+ * @returns The interpolated angle in degrees.
+ */
+declare function lerpAngle(a0: number, a1: number, t: number): number;
+
+/**
+ * The Adobe RGB (1998) color space in linear form, without a transfer function, aliased as <code>"a98-rgb-linear"</code>.
+ */
+declare const A98RGBLinear: ColorSpace;
+
+/**
+ * The Adobe RGB (1998) color space, with a transfer function, aliased as <code>"a98-rgb"</code>. Inherits from the {@link A98RGBLinear} color space.
+ */
+declare const A98RGB: ColorSpace;
+
+/**
+ * A color gamut for the {@link A98RGB}, or Adobe RGB (1998), color space.
+ */
+declare const A98RGBGamut: ColorGamut;
+
+/**
+ * The Display-P3 color space in linear form, without a transfer function, aliased as <code>"display-p3-linear"</code>.
+ */
+declare const DisplayP3Linear: ColorSpace;
+
+/**
+ * The Display-P3 color space, with a transfer function, aliased as <code>"display-p3"</code>. Inherits from the {@link DisplayP3Linear} color space.
+ */
+declare const DisplayP3: ColorSpace;
+
+/**
+ * A color gamut for the {@link DisplayP3} color space.
+ */
+declare const DisplayP3Gamut: ColorGamut;
+
+/**
+ * The OKLab color space.
+ */
+declare const OKLab: ColorSpace;
+
+/**
+ * The OKLCH color space, with Lightness, Chroma, and Hue components. This is the cylindrical form of the {@link OKLab} color space.
+ */
+declare const OKLCH: ColorSpace;
+
+/**
+ * An implementation of the OKHSL color space, fixed to the {@link sRGBGamut}. This is useful for color pickers and other applications where
+ * you wish to work with components in a well-defined and enclosed cylindrical form. If you wish to use OKHSL with a different gamut, you'll
+ * need to use the {@link OKHSLToOKLab} and {@link OKLabToOKHSL} methods directly, passing your desired gamut.
+ */
+declare const OKHSL: ColorSpace;
+
+/**
+ * An implementation of the OKHSV color space, fixed to the {@link sRGBGamut}. This is useful for color pickers and other applications where
+ * you wish to work with components in a well-defined and enclosed cylindrical form. If you wish to use OKHSL with a different gamut, you'll
+ * need to use the {@link OKHSLToOKLab} and {@link OKLabToOKHSL} methods directly, passing your desired gamut.
+ */
+declare const OKHSV: ColorSpace;
+
+/**
+ * The ProPhotoRGB color space in linear form, without a transfer function, aliased as <code>"prophoto-rgb-linear"</code>.
+ */
+declare const ProPhotoRGBLinear: ColorSpace;
+
+/**
+ * The ProPhotoRGB color space, with a transfer function, aliased as <code>"prophoto-rgb"</code>. Inherits from the {@link ProPhotoRGBLinear} color space.
+ */
+declare const ProPhotoRGB: ColorSpace;
+
+/**
+ * The Rec2020 color space in linear form, without a transfer function, aliased as <code>"rec2020-linear"</code>.
+ */
+declare const Rec2020Linear: ColorSpace;
+
+/**
+ * The Rec2020 color space, with a transfer function, aliased as <code>"rec2020"</code>. Inherits from the {@link Rec2020Linear} color space.
+ */
+declare const Rec2020: ColorSpace;
+
+/**
+ * A color gamut for the {@link Rec2020} color space.
+ */
+declare const Rec2020Gamut: ColorGamut;
+
+/**
+ * The sRGB color space in linear form, without a transfer function, aliased as <code>"srgb-linear"</code>.
+ */
+declare const sRGBLinear: ColorSpace;
+
+/**
+ * The sRGB color space, with a transfer function, aliased as <code>"srgb"</code>. Inherits from the {@link sRGBLinear} color space.
+ */
+declare const sRGB: ColorSpace;
+
+/**
+ * A color gamut for the {@link sRGB} color space.
+ */
+declare const sRGBGamut: ColorGamut;
+
+/**
+ * Converts a single sRGB gamma-corrected channel value to linear light (un-companded) form.
+ * @param val - The sRGB gamma-corrected channel value in the range [0, 1].
+ * @returns The linear light channel value.
+ */
+declare function sRGBGammaToLinear(val: number): number;
+
+/**
+ * Converts a single linear-light channel value to sRGB gamma-corrected form.
+ * @param val - The linear-light channel value in the range [0, 1].
+ * @returns The sRGB gamma-corrected channel value.
+ */
+declare function sRGBLinearToGamma(val: number): number;
+
+/**
+ * Converts a color from XYZ with D65 whitepoint to XYZ with D50 whitepoint.
+ * @param XYZ - The input color in XYZ with D65 whitepoint.
+ * @param [out = vec3()] - The output color in XYZ with D50 whitepoint.
+ * @returns The converted color in XYZ with D50 whitepoint.
+ */
+declare function XYZD65ToD50(XYZ: Vector, out?: Vector): Vector;
+
+/**
+ * Converts a color from XYZ with D50 whitepoint to XYZ with D65 whitepoint.
+ * @param XYZ - The input color in XYZ with D50 whitepoint.
+ * @param [out = vec3()] - The output color in XYZ with D65 whitepoint.
+ * @returns The converted color in XYZ with D65 whitepoint.
+ */
+declare function XYZD50ToD65(XYZ: Vector, out?: Vector): Vector;
+
+/**
+ * XYZ color space with D65 whitepoint, aliased as <code>"xyz"</code>.
+ */
+declare const XYZ: ColorSpace;
+
+/**
+ * XYZ color space with D50 whitepoint, aliased as <code>"xyz-d50"</code>.
+ */
+declare const XYZD50: ColorSpace;

package.json

 {
   "name": "@texel/color",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "a minimal and modern color library",
@@ -13,2 +13,3 @@ "type": "module",
   "devDependencies": {
+    "better-docs": "^2.7.3",
     "canvas-sketch": "^0.7.7",
@@ -20,2 +21,3 @@ "canvas-sketch-cli": "^1.11.21",
     "faucet": "^0.0.4",
+    "jsdoc": "^4.0.4",
     "pako": "^2.1.0",
@@ -25,6 +27,10 @@ "png-tools": "^1.0.4",
     "tape": "^5.8.1",
-    "terser": "^5.31.3"
+    "terser": "^5.31.3",
+    "tsd-jsdoc": "^2.5.0"
   },
+  "types": "./types/types.d.ts",
   "scripts": {
     "visualize": "canvas-sketch-cli test/canvas-graph.js --open",
+    "docs": "jsdoc -t node_modules/better-docs -c .jsdoc.json -d docs -R DOC.md",
+    "types": "jsdoc -t node_modules/tsd-jsdoc/dist -c .jsdoc.json -d types",
     "test": "faucet test/test*.js",
@@ -31,0 +37,0 @@ "bench": "node test/bench-colorjs.js",

README.md

@@ -76,4 +76,10 @@ # @texel/color
 
-## API
+## API Docs
 
+Auto-generated documentation with all exposed methods can be found here:
+
+[https://texel-org.github.io/color](https://texel-org.github.io/color)
+
+## API Details
+
 #### `output = convert(coords, fromSpace, toSpace, output = [0, 0, 0])`
@@ -80,0 +86,0 @@

src/core.js

@@ -5,2 +5,44 @@ import { clamp, floatToByte, hexToRGB, vec3 } from "./util.js";
 
+/**
+ * @typedef {number[][]} Matrix3x3
+ * @description A 3x3 matrix represented as an array of arrays.
+ * @example
+ * const matrix = [
+ *   [a, b, c],
+ *   [d, e, f],
+ *   [g, h, i]
+ * ];
+ */
+
+/**
+ * @typedef {number[]} Vector
+ * @description A n-dimensional vector represented as an array of numbers, typically in 3D (X, Y, Z).
+ * @example
+ * const vec = [ x, y, z ];
+ */
+
+/**
+ * @typedef {Object} ChromaticAdaptation
+ * @property {Matrix3x3} from the matrix to convert from the source whitepoint to the destination whitepoint
+ * @property {Matrix3x3} to the matrix to convert from the destination whitepoint to the source whitepoint
+ */
+
+/**
+ * @typedef {Object} ColorSpace
+ * @property {String} id the unique identifier for this color space in lowercase
+ * @property {Matrix3x3} [toXYZ_M] optional matrix to convert this color directly to XYZ D65
+ * @property {Matrix3x3} [fromXYZ_M] optional matrix to convert XYZ D65 to this color space
+ * @property {Matrix3x3} [toLMS_M] optional matrix to convert this color space to OKLab's LMS intermediary form
+ * @property {Matrix3x3} [fromLMS_M] optional matrix to convert OKLab's LMS intermediary form to this color space
+ * @property {ChromaticAdaptation} [adapt] optional chromatic adaptation matrices
+ * @property {ColorSpace} [base] an optional base color space that this space is derived from
+ * @property {function} [toBase] if a base color space exists, this maps the color to the base space form (e.g. gamma to the linear base space)
+ * @property {function} [fromBase] if a base color space exists, this maps the color from the base space form (e.g. the linear base space to the gamma space)
+ */
+
+/**
+ * @typedef {Object} ColorGamut
+ * @property {ColorSpace} space the color space associated with this color gamut
+ */
+
 const tmp3 = vec3();
@@ -25,2 +67,11 @@
 
+/**
+ * Converts OKLab color to another color space.
+ * @param {Vector} OKLab The OKLab color.
+ * @param {Matrix3x3} LMS_to_output The transformation matrix from LMS to the output color space.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The transformed color.
+ * @method
+ * @category oklab
+ */
 export const OKLab_to = (OKLab, LMS_to_output, out = vec3()) => {
@@ -32,2 +83,11 @@ transform(OKLab, OKLab_to_LMS_M, out);
 
+/**
+ * Converts a color from another color space to OKLab.
+ * @param {Vector} input The input color.
+ * @param {Matrix3x3} input_to_LMS The transformation matrix from the input color space to LMS.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The transformed color.
+ * @method
+ * @category oklab
+ */
 export const OKLab_from = (input, input_to_LMS, out = vec3()) => {
@@ -39,2 +99,11 @@ transform(input, input_to_LMS, out);
 
+/**
+ * Transforms a color vector by the specified 3x3 transformation matrix.
+ * @param {Vector} input The input color.
+ * @param {Matrix3x3} matrix The transformation matrix.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The transformed color.
+ * @method
+ * @category core
+ */
 export const transform = (input, matrix, out = vec3()) => {
@@ -56,2 +125,11 @@ const x = dot3(input, matrix[0]);
 
+/**
+ * Serializes a color to a CSS color string.
+ * @param {Vector} input The input color.
+ * @param {ColorSpace} inputSpace The input color space.
+ * @param {ColorSpace} [outputSpace=inputSpace] The output color space.
+ * @returns {string} The serialized color string.
+ * @method
+ * @category core
+ */
 export const serialize = (input, inputSpace, outputSpace = inputSpace) => {
@@ -94,9 +172,29 @@ if (!inputSpace) throw new Error(`must specify an input space`);
 
-const parseFloatValue = str => parseFloat(str) || 0;
+const parseFloatValue = (str) => parseFloat(str) || 0;
 
 const parseColorValue = (str, is255 = false) => {
   if (is255) return clamp(parseFloatValue(str) / 0xff, 0, 0xff);
-  else return str.includes('%') ? parseFloatValue(str) / 100 : parseFloatValue(str);
+  else
+    return str.includes("%")
+      ? parseFloatValue(str) / 100
+      : parseFloatValue(str);
 };
 
+/**
+ * Deserializes a color string to an object with <code>id</code> (color space string) and <code>coords</code> (the vector, in 3 or 4 dimensions).
+ * Note this does not return a <code>ColorSpace</code> object; you may want to use the example code below to map the string ID to a <code>ColorSpace</code>, but this will increase the size of your final bundle as it references all spaces.
+ *
+ * @example
+ * import { listColorSpaces, deserialize } from "@texel/color";
+ *
+ * const { id, coords } = deserialize(str);
+ * // now find the actual color space object
+ * const space = listColorSpaces().find((f) => id === f.id);
+ * console.log(space, coords);
+ *
+ * @param {string} input The color string to deserialize.
+ * @returns {{id: string, coords: Vector}} The deserialized color object.
+ * @method
+ * @category core
+ */
 export const deserialize = (input) => {
@@ -123,5 +221,5 @@ if (typeof input !== "string") {
     const fn = parts[1].toLowerCase();
-    if (/^rgba?$/i.test(fn) && parts[2].includes(',')) {
-      const coords = parts[2].split(',').map((v, i) => {
-        return parseColorValue(v.trim(), i < 3)
+    if (/^rgba?$/i.test(fn) && parts[2].includes(",")) {
+      const coords = parts[2].split(",").map((v, i) => {
+        return parseColorValue(v.trim(), i < 3);
       });
@@ -149,3 +247,3 @@ return {
         } else if (/rgba?/i.test(fn)) {
-          id = 'srgb';
+          id = "srgb";
           div255 = true;
@@ -179,2 +277,11 @@ } else {
 
+/**
+ * Parses a color string and converts it to the target color space.
+ * @param {string} input The color string to parse.
+ * @param {ColorSpace} targetSpace The target color space.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The parsed and converted color.
+ * @method
+ * @category core
+ */
 export const parse = (input, targetSpace, out = vec3()) => {
@@ -200,2 +307,12 @@ if (!targetSpace)
 
+/**
+ * Converts a color from one color space to another.
+ * @param {Vector} input The input color.
+ * @param {ColorSpace} fromSpace The source color space.
+ * @param {ColorSpace} toSpace The target color space.
+ * @param {Vector} [out=vec3()] The output vector.
+ * @returns {Vector} The converted color.
+ * @method
+ * @category core
+ */
 export const convert = (input, fromSpace, toSpace, out = vec3()) => {
@@ -323,4 +440,10 @@ // place into output
 
-// Calculate deltaE OK
-// simple root sum of squares
+/**
+ * Calculates the DeltaEOK (color difference) between two OKLab colors.
+ * @param {Vector} oklab1 The first OKLab color.
+ * @param {Vector} oklab2 The second OKLab color.
+ * @returns {number} The delta E value.
+ * @method
+ * @category core
+ */
 export const deltaEOK = (oklab1, oklab2) => {
@@ -327,0 +450,0 @@ let dL = oklab1[0] - oklab2[0];

src/gamut.js

@@ -15,5 +15,33 @@ import {
 
+/**
+ * @typedef {function} GamutMapMethod
+ * @description A function that maps an OKLCH color to a lightness value.
+ * @param {Vector} oklch The input OKLCH color
+ * @param {number[]} cusp A 2D cusp point in the form [L, C]
+ * @category mapping
+ */
+
+/**
+ * A {@link GamutMapMethod} that maintains the color's lightness.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToL = (oklch) => oklch[0];
+/**
+ * A {@link GamutMapMethod} that maps towards middle gray (L = 0.5).
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToGray = () => 0.5;
+/**
+ * A {@link GamutMapMethod} that maps towards the lightness of the current hue's cusp.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToCuspL = (_, cusp) => cusp[0];
+/**
+ * A {@link GamutMapMethod} that adaptively maps towards gray.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToAdaptiveGray = (oklch, cusp) => {
@@ -28,3 +56,7 @@ const Ld = oklch[0] - cusp[0];
 };
-
+/**
+ * A {@link GamutMapMethod} that adaptively maps towards the cusp's lightness.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToAdaptiveCuspL = (oklch) => {
@@ -60,2 +92,13 @@ const Ld = oklch[0] - 0.5;
 
+/**
+ * Computes the maximum saturation (S = C/L) possible for a given hue that fits within
+ * the RGB gamut, using the given coefficients.
+ * @param {number} a The normalized a component of the hue.
+ * @param {number} b The normalized b component of the hue.
+ * @param {number[][]} lmsToRgb The LMS to RGB conversion matrix.
+ * @param {number[][][]} okCoeff The OKLab coefficients.
+ * @returns {number} The maximum saturation.
+ * @method
+ * @category mapping
+ */
 export const computeMaxSaturationOKLC = (a, b, lmsToRgb, okCoeff) => {
@@ -138,2 +181,9 @@ // https://github.com/color-js/color.js/blob/main/src/spaces/okhsl.js
 
+/**
+ * Retrieves the LMS to RGB conversion matrix from the given gamut.
+ * @param {ColorGamut} gamut The gamut object.
+ * @returns {Matrix3x3} The LMS to RGB conversion matrix.
+ * @method
+ * @category mapping
+ */
 export const getGamutLMStoRGB = (gamut) => {
@@ -147,2 +197,12 @@ if (!gamut) throw new Error(`expected gamut to have { space }`);
 
+/**
+ * Finds the cusp of the OKLCH color space for a given hue.
+ * @param {number} a The normalized a component of the hue.
+ * @param {number} b The normalized b component of the hue.
+ * @param {ColorGamut} gamut The gamut object.
+ * @param {number[]} [out=[0, 0]] The output array to store the cusp values.
+ * @returns {number[]} The cusp values [L, C].
+ * @method
+ * @category mapping
+ */
 export const findCuspOKLCH = (a, b, gamut, out = [0, 0]) => {
@@ -190,3 +250,3 @@ const lmsToRgb = getGamutLMStoRGB(gamut);
   if ((l1 - l0) * cusp[1] - (cusp[0] - l0) * c1 <= 0.0) {
-    const denom = (c1 * cusp[0] + cusp[1] * (l0 - l1));
+    const denom = c1 * cusp[0] + cusp[1] * (l0 - l1);
     // Lower half
@@ -198,3 +258,3 @@ t = denom === 0 ? 0 : (cusp[1] * l0) / denom;
     // First intersect with triangle
-    const denom = (c1 * (cusp[0] - 1.0) + cusp[1] * (l0 - l1));
+    const denom = c1 * (cusp[0] - 1.0) + cusp[1] * (l0 - l1);
     t = denom === 0 ? 0 : (cusp[1] * (l0 - 1.0)) / denom;
@@ -266,3 +326,13 @@
 /**
- * Takes any OKLCH value and maps it to fall within the given gamut.
+ * Applies fast approximate gamut mapping in OKLab space on the given OKLCH input color,
+ * using the specified gamut and converting to the target color space.
+ * @param {Vector} oklch The input OKLCH color that you wish to gamut map.
+ * @param {ColorGamut} [gamut=sRGBGamut] The gamut object.
+ * @param {ColorSpace} [targetSpace=gamut.space] The target color space.
+ * @param {Vector} [out=vec3()] The output array to store the mapped color.
+ * @param {GamutMapMethod} [mapping=MapToCuspL] The gamut mapping function.
+ * @param {Vector} [cusp] Optional, you can provide the cusp values [L, C] to avoid re-computing them.
+ * @returns {Vector} The mapped color in the target color space.
+ * @method
+ * @category mapping
  */
@@ -269,0 +339,0 @@ export const gamutMapOKLCH = (

src/okhsl.js

@@ -119,2 +119,12 @@ import { vec3, constrainAngle as constrain } from "./util.js";
 
+/**
+ * Converts OKHSL color to OKLab color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} hsl - The OKHSL color as an array [h, s, l].
+ * @param {ColorGamut} [gamut=sRGBGamut] - The color gamut.
+ * @param {Vector} [out=vec3()] - The output array to store the OKLab color.
+ * @returns {Vector} The OKLab color as an array [L, a, b].
+ */
 export const OKHSLToOKLab = (hsl, gamut = sRGBGamut, out = vec3()) => {
@@ -175,2 +185,12 @@ // Convert Okhsl to Oklab.
 
+/**
+ * Converts OKLab color to OKHSL color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} lab - The OKLab color as an array [L, a, b].
+ * @param {ColorGamut} [gamut=sRGBGamut] - The color gamut.
+ * @param {Vector} [out=vec3()] - The output array to store the OKHSL color.
+ * @returns {Vector} The OKHSL color as an array [h, s, l].
+ */
 export const OKLabToOKHSL = (lab, gamut = sRGBGamut, out = vec3()) => {
@@ -239,2 +259,12 @@ // Oklab to Okhsl.
 
+/**
+ * Converts OKHSV color to OKLab color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} hsv - The OKHSV color as an array [h, s, v].
+ * @param {ColorGamut} [gamut=sRGBGamut] - The color gamut.
+ * @param {Vector} [out=vec3()] - The output array to store the OKLab color.
+ * @returns {Vector} The OKLab color as an array [L, a, b].
+ */
 export const OKHSVToOKLab = (hsv, gamut = sRGBGamut, out = vec3()) => {
@@ -294,2 +324,12 @@ // Convert from Okhsv to Oklab."""
 
+/**
+ * Converts OKLab color to OKHSV color.
+ *
+ * @method
+ * @category oklab
+ * @param {Vector} lab The OKLab color as an array [L, a, b].
+ * @param {ColorGamut} [gamut=sRGBGamut] The color gamut.
+ * @param {Vector} [out=vec3()] The output array to store the OKHSV color.
+ * @returns {Vector} The OKHSV color as an array [h, s, v].
+ */
 export const OKLabToOKHSV = (lab, gamut = sRGBGamut, out = vec3()) => {
@@ -296,0 +336,0 @@ // Oklab to Okhsv.

src/spaces.js

@@ -21,2 +21,9 @@ import { XYZ, XYZD50 } from "./spaces/xyz.js";
 
+/**
+ * Returns a list of color spaces.
+ *
+ * @method
+ * @returns {ColorSpace[]} An array of color space objects.
+ * @category core
+ */
 export const listColorSpaces = () => {
@@ -43,4 +50,11 @@ return [
 
+/**
+ * Returns a list of color gamuts.
+ *
+ * @method
+ * @returns {ColorGamut[]} An array of color gamut objects.
+ * @category core
+ */
 export const listColorGamuts = () => {
   return [sRGBGamut, DisplayP3Gamut, Rec2020Gamut, A98RGBGamut];
 };

src/spaces/a98-rgb.js

@@ -22,2 +22,7 @@ import { vec3 } from "../util.js";
 
+/**
+ * The Adobe RGB (1998) color space in linear form, without a transfer function, aliased as <code>"a98-rgb-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const A98RGBLinear = {
@@ -31,2 +36,7 @@ id: "a98-rgb-linear",
 
+/**
+ * The Adobe RGB (1998) color space, with a transfer function, aliased as <code>"a98-rgb"</code>. Inherits from the {@link A98RGBLinear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const A98RGB = {
@@ -49,2 +59,7 @@ id: "a98-rgb",
 
+/**
+ * A color gamut for the {@link A98RGB}, or Adobe RGB (1998), color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const A98RGBGamut = {
@@ -51,0 +66,0 @@ space: A98RGB,

src/spaces/display-p3.js

@@ -10,2 +10,7 @@ import {
 
+/**
+ * The Display-P3 color space in linear form, without a transfer function, aliased as <code>"display-p3-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const DisplayP3Linear = {
@@ -19,2 +24,7 @@ id: "display-p3-linear",
 
+/**
+ * The Display-P3 color space, with a transfer function, aliased as <code>"display-p3"</code>. Inherits from the {@link DisplayP3Linear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const DisplayP3 = {
@@ -27,2 +37,7 @@ id: "display-p3",
 
+/**
+ * A color gamut for the {@link DisplayP3} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const DisplayP3Gamut = {
@@ -29,0 +44,0 @@ space: DisplayP3,

src/spaces/oklab.js

@@ -16,2 +16,7 @@ // Oklab and related spaces: OKLCH, OKHSV(sRGB), OKHSL(sRGB)
 
+/**
+ * The OKLab color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKLab = {
@@ -21,2 +26,7 @@ id: "oklab",
 
+/**
+ * The OKLCH color space, with Lightness, Chroma, and Hue components. This is the cylindrical form of the {@link OKLab} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKLCH = {
@@ -56,2 +66,9 @@ id: "oklch",
 
+/**
+ * An implementation of the OKHSL color space, fixed to the {@link sRGBGamut}. This is useful for color pickers and other applications where
+ * you wish to work with components in a well-defined and enclosed cylindrical form. If you wish to use OKHSL with a different gamut, you'll
+ * need to use the {@link OKHSLToOKLab} and {@link OKLabToOKHSL} methods directly, passing your desired gamut.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKHSL = {
@@ -66,2 +83,9 @@ // Note: sRGB gamut only
 
+/**
+ * An implementation of the OKHSV color space, fixed to the {@link sRGBGamut}. This is useful for color pickers and other applications where
+ * you wish to work with components in a well-defined and enclosed cylindrical form. If you wish to use OKHSL with a different gamut, you'll
+ * need to use the {@link OKHSLToOKLab} and {@link OKLabToOKHSL} methods directly, passing your desired gamut.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKHSV = {
@@ -68,0 +92,0 @@ // Note: sRGB gamut only

src/spaces/prophoto-rgb.js

@@ -38,2 +38,7 @@ import { vec3 } from "../util.js";
 
+/**
+ * The ProPhotoRGB color space in linear form, without a transfer function, aliased as <code>"prophoto-rgb-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const ProPhotoRGBLinear = {
@@ -51,2 +56,7 @@ id: "prophoto-rgb-linear",
 
+/**
+ * The ProPhotoRGB color space, with a transfer function, aliased as <code>"prophoto-rgb"</code>. Inherits from the {@link ProPhotoRGBLinear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const ProPhotoRGB = {
@@ -53,0 +63,0 @@ id: "prophoto-rgb",

src/spaces/rec2020.js

@@ -19,2 +19,7 @@ import { vec3 } from "../util.js";
 
+/**
+ * The Rec2020 color space in linear form, without a transfer function, aliased as <code>"rec2020-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const Rec2020Linear = {
@@ -28,2 +33,7 @@ id: "rec2020-linear",
 
+/**
+ * The Rec2020 color space, with a transfer function, aliased as <code>"rec2020"</code>. Inherits from the {@link Rec2020Linear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const Rec2020 = {
@@ -46,2 +56,7 @@ id: "rec2020",
 
+/**
+ * A color gamut for the {@link Rec2020} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const Rec2020Gamut = {
@@ -48,0 +63,0 @@ space: Rec2020,

src/spaces/srgb.js

@@ -11,2 +11,7 @@ import {
 
+/**
+ * The sRGB color space in linear form, without a transfer function, aliased as <code>"srgb-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const sRGBLinear = {
@@ -20,2 +25,7 @@ id: "srgb-linear",
 
+/**
+ * The sRGB color space, with a transfer function, aliased as <code>"srgb"</code>. Inherits from the {@link sRGBLinear} color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const sRGB = {
@@ -28,2 +38,7 @@ id: "srgb",
 
+/**
+ * A color gamut for the {@link sRGB} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const sRGBGamut = {
@@ -30,0 +45,0 @@ space: sRGB,

src/spaces/util.js

 import { vec3 } from "../util.js";
 
+/**
+ * Converts a single sRGB gamma-corrected channel value to linear light (un-companded) form.
+ * @param {number} val - The sRGB gamma-corrected channel value in the range [0, 1].
+ * @returns {number} The linear light channel value.
+ * @method
+ * @category rgb
+ */
 export const sRGBGammaToLinear = (val) => {
@@ -18,2 +25,9 @@ // convert a single channel value
 
+/**
+ * Converts a single linear-light channel value to sRGB gamma-corrected form.
+ * @param {number} val - The linear-light channel value in the range [0, 1].
+ * @returns {number} The sRGB gamma-corrected channel value.
+ * @method
+ * @category rgb
+ */
 export const sRGBLinearToGamma = (val) => {
@@ -20,0 +34,0 @@ // convert a single channel linear-light value in range 0-1

src/spaces/xyz.js

@@ -31,9 +31,29 @@ import { vec3 } from "../util.js";
 
+/**
+ * Converts a color from XYZ with D65 whitepoint to XYZ with D50 whitepoint.
+ * @method
+ * @category xyz
+ * @param {Vector} XYZ - The input color in XYZ with D65 whitepoint.
+ * @param {Vector} [out=vec3()] - The output color in XYZ with D50 whitepoint.
+ * @returns {Vector} The converted color in XYZ with D50 whitepoint.
+ */
 export const XYZD65ToD50 = (XYZ, out = vec3()) =>
   transform(XYZ, D65_to_D50_M, out);
 
+/**
+ * Converts a color from XYZ with D50 whitepoint to XYZ with D65 whitepoint.
+ * @method
+ * @category xyz
+ * @param {Vector} XYZ - The input color in XYZ with D50 whitepoint.
+ * @param {Vector} [out=vec3()] - The output color in XYZ with D65 whitepoint.
+ * @returns {Vector} The converted color in XYZ with D65 whitepoint.
+ */
 export const XYZD50ToD65 = (XYZ, out = vec3()) =>
   transform(XYZ, D50_to_D65_M, out);
 
-// XYZ using D65 whitepoint
+/**
+ * XYZ color space with D65 whitepoint, aliased as <code>"xyz"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const XYZ = {
@@ -45,3 +65,7 @@ id: "xyz", // xyz-d65
 
-// XYZ using D50 whitepoint
+/**
+ * XYZ color space with D50 whitepoint, aliased as <code>"xyz-d50"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const XYZD50 = {
@@ -48,0 +72,0 @@ id: "xyz-d50",

src/util.js

@@ -1,13 +0,58 @@
-const GAMUT_EPSILON = 0.000075;
-
+/**
+ * Clamps a value between a minimum and maximum value.
+ * @method
+ * @param {number} value The value to clamp.
+ * @param {number} min The minimum value.
+ * @param {number} max The maximum value.
+ * @returns {number} The clamped value.
+ * @category utils
+ */
 export const clamp = (value, min, max) => Math.max(Math.min(value, max), min);
 
+/**
+ * Linearly interpolates between two values.
+ * @method
+ * @param {number} min The start value.
+ * @param {number} max The end value.
+ * @param {number} t The interpolation factor between 0 and 1.
+ * @returns {number} The interpolated value.
+ * @category utils
+ */
 export const lerp = (min, max, t) => min * (1 - t) + max * t;
 
+/**
+ * Converts degrees to radians.
+ * @method
+ * @param {number} n The angle in degrees.
+ * @returns {number} The angle in radians.
+ * @category utils
+ */
 export const degToRad = (n) => (n * Math.PI) / 180;
 
+/**
+ * Converts radians to degrees.
+ * @method
+ * @param {number} n The angle in radians.
+ * @returns {number} The angle in degrees.
+ * @category utils
+ */
 export const radToDeg = (n) => (n * 180) / Math.PI;
 
+/**
+ * Constrains an angle to the range [0, 360).
+ * @method
+ * @param {number} angle The angle in degrees.
+ * @returns {number} The constrained angle.
+ * @category utils
+ */
 export const constrainAngle = (angle) => ((angle % 360) + 360) % 360;
 
+/**
+ * Converts a hex color string to an RGB array.
+ * @method
+ * @param {string} str The hex color string.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The RGB array.
+ * @category rgb
+ */
 export const hexToRGB = (str, out = vec3()) => {
@@ -29,8 +74,27 @@ let hex = str.replace(/#/, "");
 
+/**
+ * Converts an RGB array to a hex color string.
+ * @method
+ * @param {Vector} rgb The RGB array.
+ * @returns {string} The hex color string.
+ * @category rgb
+ */
 export const RGBToHex = (rgb) =>
   `#${rgb.map((n) => floatToByte(n).toString(16).padStart(2, "0")).join("")}`;
 
-/** @deprecated use RGBToHex */
+/**
+ * @method
+ * @deprecated Use RGBToHex instead.
+ * @category rgb
+ */
 export const RGBtoHex = RGBToHex;
 
+/**
+ * Checks if an RGB color is within the gamut.
+ * @method
+ * @param {Vector} lrgb The linear RGB array.
+ * @param {number} [ep=GAMUT_EPSILON] The epsilon value for comparison.
+ * @returns {boolean} True if the color is within the gamut, false otherwise.
+ * @category rgb
+ */
 export const isRGBInGamut = (lrgb, ep = GAMUT_EPSILON) => {
@@ -50,2 +114,10 @@ const r = lrgb[0];
 
+/**
+ * Clamps an RGB array to the range [0, 1].
+ * @method
+ * @param {Vector} rgb The RGB array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The clamped RGB array.
+ * @category rgb
+ */
 export const clampedRGB = (rgb, out = vec3()) => {
@@ -58,2 +130,10 @@ out[0] = clamp(rgb[0], 0, 1);
 
+/**
+ * Converts xyY color space to XYZ color space.
+ * @method
+ * @param {Vector} arg The xyY array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The XYZ array.
+ * @category xyz
+ */
 export const xyY_to_XYZ = (arg, out = vec3()) => {
@@ -76,2 +156,10 @@ let X, Y, Z, x, y;
 
+/**
+ * Converts XYZ color space to xyY color space.
+ * @method
+ * @param {Vector} arg The XYZ array.
+ * @param {Vector} [out=vec3()] The output array.
+ * @returns {Vector} The xyY array.
+ * @category xyz
+ */
 export const XYZ_to_xyY = (arg, out = vec3()) => {
@@ -94,22 +182,27 @@ let sum, X, Y, Z;
 
+/**
+ * Converts a float value to a byte value.
+ * @method
+ * @param {number} n The float value.
+ * @returns {number} The byte value.
+ * @category utils
+ */
 export const floatToByte = (n) => clamp(Math.round(255 * n), 0, 255);
 
-// Undocumented
-
+/**
+ * Creates a new vec3 array.
+ * @method
+ * @returns {Vector} The vec3 array.
+ * @category utils
+ */
 export const vec3 = () => [0, 0, 0];
 
-// export const normalizeHue = (hue) => ((hue = hue % 360) < 0 ? hue + 360 : hue);
-
-// in degrees
-// export const angle_delta = (angle1, angle2) => {
-//   const diff = ((angle2 - angle1 + 180) % 360) - 180;
-//   return diff < -180 ? diff + 360 : diff;
-// };
-
-// function shortAngleDistRad(a0, a1) {
-//   var max = Math.PI * 2;
-//   var da = (a1 - a0) % max;
-//   return ((2 * da) % max) - da;
-// }
-
+/**
+ * Calculates the delta angle between two angles.
+ * @method
+ * @param {number} a0 The first angle in degrees.
+ * @param {number} a1 The second angle in degrees.
+ * @returns {number} The delta angle in degrees.
+ * @category utils
+ */
 export const deltaAngle = (a0, a1) => {
@@ -120,2 +213,11 @@ var da = (a1 - a0) % 360;
 
+/**
+ * Linearly interpolates between two angles.
+ * @method
+ * @param {number} a0 The start angle in degrees.
+ * @param {number} a1 The end angle in degrees.
+ * @param {number} t The interpolation factor between 0 and 1.
+ * @returns {number} The interpolated angle in degrees.
+ * @category utils
+ */
 export const lerpAngle = (a0, a1, t) => a0 + deltaAngle(a0, a1) * t;

No alert changes

Improved metrics

Total package byte prevSize

109408

47.15%

Number of package files

21

16.67%

Lines of code

2536

62.98%

Number of lines in readme file

459

1.32%

Worsened metrics

Dev dependency count

14

27.27%

No dependency changes