@texel/color 1.1.3 → 1.1.5

package/.jsdoc.json

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

package/DOC.md

@@ -0,0 +1,17 @@
+`@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.

package/README.md

@@ -73,7 +73,13 @@ context.fillStyle = color;
 context.fillRect(0,0, canvas.width, canvas.height);
 ```
 
-## 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])`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@texel/color",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "a minimal and modern color library",
   "type": "module",
   "main": "./src/index.js",
@@ -10,20 +10,26 @@
     "url": "https://github.com/mattdesl"
   },
   "devDependencies": {
+    "better-docs": "^2.7.3",
     "canvas-sketch": "^0.7.7",
     "canvas-sketch-cli": "^1.11.21",
     "colorjs.io": "^0.5.2",
     "culori": "^4.0.1",
     "esbuild": "^0.23.0",
     "faucet": "^0.0.4",
+    "jsdoc": "^4.0.4",
     "pako": "^2.1.0",
     "png-tools": "^1.0.4",
     "prettier": "^3.3.3",
     "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",
     "bench": "node test/bench-colorjs.js",
     "bench:node": "NODE_ENV=production node --prof --no-logfile-per-isolate test/bench-node.js && node --prof-process v8.log",

package/src/core.js

@@ -2,6 +2,48 @@ import { clamp, floatToByte, hexToRGB, vec3 } from "./util.js";
 import { LMS_to_OKLab_M, OKLab_to_LMS_M } from "./conversion_matrices.js";
 import { listColorSpaces, sRGB, XYZ } from "./spaces.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();
 
 const cubed3 = (lms) => {
@@ -21,18 +63,45 @@ const cbrt3 = (lms) => {
 
 const dot3 = (a, b) => a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
 
+/**
+ * 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()) => {
   transform(OKLab, OKLab_to_LMS_M, out);
   cubed3(out);
   return transform(out, LMS_to_output, 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()) => {
   transform(input, input_to_LMS, out);
   cbrt3(out);
   return transform(out, LMS_to_OKLab_M, 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()) => {
   const x = dot3(input, matrix[0]);
   const y = dot3(input, matrix[1]);
@@ -49,6 +118,15 @@ const vec3Copy = (input, output) => {
   output[2] = input[2];
 };
 
+/**
+ * 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) => {
   if (!inputSpace) throw new Error(`must specify an input space`);
   // extract alpha if present
@@ -86,13 +164,33 @@ const stripAlpha = (coords) => {
   return coords;
 };
 
-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) => {
   if (typeof input !== "string") {
     throw new Error(`expected a string as input`);
@@ -114,9 +212,9 @@ export const deserialize = (input) => {
       throw new Error(`could not parse color string ${input}`);
     }
     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);
       });
       return {
         id: "srgb",
@@ -139,7 +237,7 @@ export const deserialize = (input) => {
         if (/^(oklab|oklch)$/i.test(fn)) {
           id = fn;
         } else if (/rgba?/i.test(fn)) {
-          id = 'srgb';
+          id = "srgb";
           div255 = true;
         } else {
           throw new Error(`unknown color function ${fn}`);
@@ -168,6 +266,15 @@ export const deserialize = (input) => {
   }
 };
 
+/**
+ * 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()) => {
   if (!targetSpace)
     throw new Error(`must specify a target space to parse into`);
@@ -188,6 +295,16 @@ export const parse = (input, targetSpace, out = vec3()) => {
   return out;
 };
 
+/**
+ * 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()) => {
   // place into output
   vec3Copy(input, out);
@@ -310,8 +427,14 @@ export const convert = (input, fromSpace, toSpace, out = vec3()) => {
   return out;
 };
 
-// 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) => {
   let dL = oklab1[0] - oklab2[0];
   let da = oklab1[1] - oklab2[1];

package/src/gamut.js

@@ -12,9 +12,37 @@ import { OKLab_to, convert } from "./core.js";
 
 const DEFAULT_ALPHA = 0.05;
 
+/**
+ * @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) => {
   const Ld = oklch[0] - cusp[0];
   const k = 2 * (Ld > 0 ? 1 - cusp[0] : cusp[0]);
@@ -24,7 +52,11 @@ export const MapToAdaptiveGray = (oklch, cusp) => {
     0.5 * (Math.sign(Ld) * (e1 - Math.sqrt(e1 * e1 - 2 * k * Math.abs(Ld))))
   );
 };
-
+/**
+ * A {@link GamutMapMethod} that adaptively maps towards the cusp's lightness.
+ * @type {GamutMapMethod}
+ * @category mapping
+ */
 export const MapToAdaptiveCuspL = (oklch) => {
   const Ld = oklch[0] - 0.5;
   const e1 = 0.5 + Math.abs(Ld) + DEFAULT_ALPHA * oklch[1];
@@ -55,6 +87,17 @@ const setYZ = (v, a, b) => {
   v[2] = b;
 };
 
+/**
+ * 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) => {
   // https://github.com/color-js/color.js/blob/main/src/spaces/okhsl.js
   // Finds the maximum saturation possible for a given hue that fits in RGB.
@@ -132,6 +175,13 @@ export const computeMaxSaturationOKLC = (a, b, lmsToRgb, okCoeff) => {
   return sat;
 };
 
+/**
+ * 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) => {
   if (!gamut) throw new Error(`expected gamut to have { space }`);
   const lmsToRGB = (gamut.space.base ?? gamut.space).fromLMS_M;
@@ -140,6 +190,16 @@ export const getGamutLMStoRGB = (gamut) => {
   return lmsToRGB;
 };
 
+/**
+ * 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]) => {
   const lmsToRgb = getGamutLMStoRGB(gamut);
   const okCoeff = gamut.coefficients;
@@ -182,14 +242,14 @@ export const findGamutIntersectionOKLCH = (a, b, l1, c1, l0, cusp, gamut) => {
 
   // Find the intersection for upper and lower half separately
   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
     t = denom === 0 ? 0 : (cusp[1] * l0) / denom;
   } else {
     // Upper half
 
     // 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;
 
     // Then one step Halley's method
@@ -256,7 +316,17 @@ export const findGamutIntersectionOKLCH = (a, b, l1, c1, l0, cusp, gamut) => {
 };
 
 /**
- * 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
  */
 export const gamutMapOKLCH = (
   oklch,

package/src/okhsl.js

@@ -116,6 +116,16 @@ const getCs = (l, a, b, cusp, gamut) => {
   return [c0, cMid, cMax];
 };
 
+/**
+ * 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()) => {
   // Convert Okhsl to Oklab.
   let h = hsl[0],
@@ -171,6 +181,16 @@ export const OKHSLToOKLab = (hsl, gamut = sRGBGamut, out = vec3()) => {
   return out;
 };
 
+/**
+ * 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()) => {
   // Oklab to Okhsl.
 
@@ -234,6 +254,16 @@ export const OKLabToOKHSL = (lab, gamut = sRGBGamut, out = vec3()) => {
   return out;
 };
 
+/**
+ * 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()) => {
   // Convert from Okhsv to Oklab."""
 
@@ -288,6 +318,16 @@ export const OKHSVToOKLab = (hsv, gamut = sRGBGamut, out = vec3()) => {
   return out;
 };
 
+/**
+ * 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()) => {
   // Oklab to Okhsv.
   const lmsToRgb = getGamutLMStoRGB(gamut);

package/src/spaces/a98-rgb.js

@@ -19,6 +19,11 @@ const A98RGBToGamma = (val) => {
   return sign * Math.pow(abs, 256 / 563);
 };
 
+/**
+ * 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 = {
   id: "a98-rgb-linear",
   toXYZ_M: linear_A98RGB_to_XYZ_M,
@@ -27,6 +32,11 @@ export const A98RGBLinear = {
   fromLMS_M: LMS_to_linear_A98RGB_M,
 };
 
+/**
+ * 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 = {
   id: "a98-rgb",
   base: A98RGBLinear,
@@ -44,6 +54,11 @@ export const A98RGB = {
   },
 };
 
+/**
+ * A color gamut for the {@link A98RGB}, or Adobe RGB (1998), color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const A98RGBGamut = {
   space: A98RGB,
   coefficients: OKLab_to_linear_A98RGB_coefficients,

package/src/spaces/display-p3.js

@@ -7,6 +7,11 @@ import {
 } from "../conversion_matrices.js";
 import { sRGBGammaToLinearVec3, sRGBLinearToGammaVec3 } from "./util.js";
 
+/**
+ * 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 = {
   id: "display-p3-linear",
   toXYZ_M: linear_DisplayP3_to_XYZ_M,
@@ -15,6 +20,11 @@ export const DisplayP3Linear = {
   fromLMS_M: LMS_to_linear_DisplayP3_M,
 };
 
+/**
+ * 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 = {
   id: "display-p3",
   base: DisplayP3Linear,
@@ -22,6 +32,11 @@ export const DisplayP3 = {
   fromBase: sRGBLinearToGammaVec3,
 };
 
+/**
+ * A color gamut for the {@link DisplayP3} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const DisplayP3Gamut = {
   space: DisplayP3,
   coefficients: OKLab_to_linear_DisplayP3_coefficients,

package/src/spaces/oklab.js

@@ -13,10 +13,20 @@ import { sRGBGamut } from "./srgb.js";
 // based on colorjs.io, could perhaps use a more specific number than this
 const ACHROMATIC_EPSILON = (0.4 - 0.0) / 100000;
 
+/**
+ * The OKLab color space.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const OKLab = {
   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 = {
   id: "oklch",
   base: OKLab,
@@ -51,6 +61,13 @@ export const 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 = {
   // Note: sRGB gamut only
   // For other gamuts, use okhsl method directly
@@ -60,6 +77,13 @@ export const OKHSL = {
   fromBase: (oklab, out = vec3()) => OKLabToOKHSL(oklab, sRGBGamut, out),
 };
 
+/**
+ * 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 = {
   // Note: sRGB gamut only
   // For other gamuts, use okhsv method directly

package/src/spaces/prophoto-rgb.js

@@ -35,6 +35,11 @@ const ProPhotoRGBToGamma = (v) => (v >= Et ? v ** (1 / 1.8) : 16 * v);
 //   return abs >= Et ? sign * Math.pow(abs, 1 / 1.8) : 16 * val;
 // };
 
+/**
+ * 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 = {
   id: "prophoto-rgb-linear",
   adapt: {
@@ -47,6 +52,11 @@ export const ProPhotoRGBLinear = {
   fromXYZ_M: XYZ_to_linear_ProPhotoRGB_M,
 };
 
+/**
+ * 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 = {
   id: "prophoto-rgb",
   base: ProPhotoRGBLinear,

package/src/spaces/rec2020.js

@@ -16,6 +16,11 @@ const Rec2020ToLinear = (val) =>
 const Rec2020ToGamma = (val) =>
   val >= BETA ? ALPHA * Math.pow(val, 0.45) - (ALPHA - 1) : 4.5 * val;
 
+/**
+ * The Rec2020 color space in linear form, without a transfer function, aliased as <code>"rec2020-linear"</code>.
+ * @type {ColorSpace}
+ * @category spaces
+ */
 export const Rec2020Linear = {
   id: "rec2020-linear",
   toXYZ_M: linear_Rec2020_to_XYZ_M,
@@ -24,6 +29,11 @@ export const Rec2020Linear = {
   fromLMS_M: LMS_to_linear_Rec2020_M,
 };
 
+/**
+ * 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 = {
   id: "rec2020",
   base: Rec2020Linear,
@@ -41,6 +51,11 @@ export const Rec2020 = {
   },
 };
 
+/**
+ * A color gamut for the {@link Rec2020} color space.
+ * @type {ColorGamut}
+ * @category gamuts
+ */
 export const Rec2020Gamut = {
   space: Rec2020,
   coefficients: OKLab_to_linear_Rec2020_coefficients,