Adds methods: inGamut(), clampGamut() (#165)

Author: danburzo

docs/api.md

@@ -62,6 +62,7 @@ codebase: 'https://github.com/evercoder/culori/blob/main'
 <li><a href='#color-spaces'>hsl</a></li>
 <li><a href='#color-spaces'>hsv</a></li>
 <li><a href='#color-spaces'>hwb</a></li>
+<li><a href='#inGamut'>inGamut</a></li>
 <li><a href='#interpolate'>interpolate</a></li>
 <li><a href='#interpolateWith'>interpolateWith</a></li>
 <li><a href='#interpolateWithPremultipliedAlpha'>interpolateWithPremultipliedAlpha</a></li>
@@ -100,6 +101,7 @@ codebase: 'https://github.com/evercoder/culori/blob/main'
 <li><a href='#color-spaces'>rgb</a></li>
 <li><a href='#round'>round</a></li>
 <li><a href='#samples'>samples</a></li>
+<li><a href='#toGamut'>toGamut</a></li>
 <li><a href='#unlerp'>unlerp</a></li>
 <li><a href='#useMode'>useMode</a></li>
 <li><a href='#wcagContrast'>wcagContrast</a></li>
@@ -277,23 +279,43 @@ formatCss({ mode: 'lrgb', r: 0.5, s: 0.25, b: 1, alpha: 0.25 });
 // ⇒ 'color(--srgb-linear 0.5 0.25 1 / 0.25)'
 ```
 
-## Clamping
+## Gamut mapping
 
 Some color spaces (Lab and LCh in particular) allow you to express colors that can't be displayed on-screen. The methods below allow you to identify when that's the case and to produce displayable versions of the colors.
 
+<a id="inGamut" href="#inGamut">#</a> **inGamut**(_mode = "rgb"_) → _function (color | string)_
+
+<span aria-label='Source:'>☞</span> [src/clamp.js]({{codebase}}/src/clamp.js)
+
+Given a color space, returns a function with which to check whether a particular color is within the gamut of that color space. 
+
+This is meant to be used with RGB-based color spaces and their derivates (`hsl`, `hsv`, etc.). If the color space has no gamut limits, the function will always return `true`, regardless of the color passed to it. To find out which color spaces have gamut limits, see the [Color Spaces](/color-spaces/) page.
+
+```js
+import { inGamut } from 'culori';
+
+const inRgb = inGamut('rgb');
+
+inRgb('red');
+// ⇒ true
+
+inRgb('color(srgb 1.1 0 0)');
+// ⇒ false
+```
+
 <a id="displayable" href="#displayable">#</a> **displayable**(_color_ or _string_) → _boolean_
 
-<span aria-label='Source:'>☞</span> [src/displayable.js]({{codebase}}/src/displayable.js)
+<span aria-label='Source:'>☞</span> [src/clamp.js]({{codebase}}/src/clamp.js)
 
-Checks whether a particular color fits inside the sRGB gamut, by verifying that the `r`, `g`, and `b` channels are all in the interval `[0, 1]`.
+Checks whether a particular color fits inside the sRGB gamut. Equivalent to `inGamut('rgb')`.
 
 ```js
 import { displayable } from 'culori';
 
 displayable('red');
 // ⇒ true
 
-displayable('rgb(300 255 255)');
+displayable('color(srgb 1.1 0 0)');
 // ⇒ false
 ```
 
@@ -315,6 +337,26 @@ clampRgb('lab(50% 100 100)');
 // ⇒ { mode: "lab", l: 54.29…, a: 80.81…, b: 69.88… }
 ```
 
+<a id="clampGamut" href="#clampGamut">#</a> **clampGamut**(_mode = 'rgb'_) → _function(color | string)_
+
+This function extends the functionality of `clampRgb` to other color spaces. Given a color space, it returns a function with which to obtain colors within the gamut of that color space. 
+
+If the color space has no gamut limits, colors are returned unchanged. To find out which color spaces have gamut limits, see the [Color Spaces](/color-spaces/) page.
+
+The in-gamut color is always returned in the color space of the original color.
+
+```js
+import { formatCss, clampGamut } from 'culori';
+
+const crimson = 'color(display-p3 0.8 0.1 0.3)';
+const toRgb = clampGamut('rgb');
+
+formatCss(toRgb(crimson));
+// ⇒ 'color(display-p3 0.801… 0.169… 0.302…)'
+```
+
+<span aria-label='Source:'>☞</span> [src/clamp.js]({{codebase}}/src/clamp.js)
+
 <a id="clampChroma" href="#clampChroma">#</a> **clampChroma**(_color_ or _string_, _mode = 'lch'_) → _color_
 
 <span aria-label='Source:'>☞</span> [src/clamp.js]({{codebase}}/src/clamp.js)

docs/color-spaces.md

@@ -39,37 +39,48 @@ The [sRGB color space](https://en.wikipedia.org/wiki/SRGB), which most people re
 
 Serialized as `color(srgb r g b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 #### `lrgb`
 
 The linear-light form of the sRGB color space.
 
 Serialized as `color(srgb-linear r g b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 #### `a98`
 
 The A98 RGB color space, compatible with the [Adobe RGB (1998) color space](https://en.wikipedia.org/wiki/Adobe_RGB_color_space).
 
 Serialized as `color(a98-rgb r g b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 #### `p3`
 
 The [Display P3 color space](https://en.wikipedia.org/wiki/DCI-P3#Display_P3).
 
 Serialized as `color(display-p3 r g b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
 
 #### `prophoto`
 
 The [ProPhoto RGB color space](https://en.wikipedia.org/wiki/ProPhoto_RGB_color_space).
 
 Serialized as `color(prophoto-rgb r g b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 #### `rec2020`
 
 The [Rec. 2020 color space](https://en.wikipedia.org/wiki/Rec._2020).
 
 Serialized as `color(rec2020 r g b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 ### The HSL/HSV/HSI family
 
 [HSL, HSV, and HSI](https://en.wikipedia.org/wiki/HSL_and_HSV) are alternative representations of the RGB color model, created in an attempt to provide a more intuitive way to specify colors.
@@ -90,6 +101,8 @@ The HSL color space.
 
 Serialized as `hsl(h s% l%)`. A missing hue is serialized as `0`, with the `none` keyword for any other missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 #### `hsv`
 
 The HSV color space.
@@ -102,6 +115,8 @@ The HSV color space.
 
 Serialized as `color(--hsv h s v)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 #### `hsi`
 
 The HSI color space.
@@ -114,6 +129,8 @@ The HSI color space.
 
 Serialized as `color(--hsi h s i)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 ### HWB
 
 [The HWB color model](https://en.wikipedia.org/wiki/HWB_color_model) was developed by Alvy Ray Smith, who also created the HSV color model. It's meant to be more intuitive for humans to use and faster to compute.
@@ -128,6 +145,8 @@ Serialized as `hwb(h w% b%)`.
 
 Serialized as `hwb(h w% b%)`. A missing hue is serialized as `0`, with the `none` keyword for any other missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Has gamut limits.
+
 > Smith, Alvy Ray (1996) — ["HWB — A More Intuitive Hue-Based Color Model"](http://alvyray.com/Papers/CG/HWB_JGTv208.pdf), Journal of Graphics, GPU and Game tools.
 
 ### CIELAB
@@ -146,6 +165,8 @@ The CIELAB color space using the [D50 standard illuminant](https://en.wikipedia.
 
 Serialized as `lab(l a b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `lch`
 
 The CIELCh color space using the D50 standard illuminant.
@@ -158,6 +179,8 @@ The CIELCh color space using the D50 standard illuminant.
 
 Serialized as `lch(l c h)`. A missing hue is serialized as `0`, with the `none` keyword for any other missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `lab65`
 
 CIELAB relative to the D65 standard illuminant.
@@ -170,6 +193,8 @@ CIELAB relative to the D65 standard illuminant.
 
 Serialized as `color(--lab-d65 l a b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `lch65`
 
 CIELCh relative to the D65 standard illuminant.
@@ -182,6 +207,8 @@ CIELCh relative to the D65 standard illuminant.
 
 Serialized as `color(--lch-d65 l c h)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 ### CIELUV
 
 The [CIELUV color space](https://en.wikipedia.org/wiki/CIELUV) in Cartesian (Luv) and cylindrical (LCh) forms, using the D50 standard illuminant.
@@ -202,6 +229,8 @@ let deltaE_uv = culori.colorDifferenceEuclidean('luv');
 
 Serialized as `color(--luv l u v)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `lchuv`
 
 | Channel | Range           | Description |
@@ -212,6 +241,8 @@ Serialized as `color(--luv l u v)`, with the `none` keyword for any missing colo
 
 Serialized as `color(--lchuv l c h)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 ### DIN99 Lab / LCh
 
 The [DIN99](https://de.wikipedia.org/wiki/DIN99-Farbraum) color space "squishes" the CIELAB D65 color space to obtain an [effective color difference](#culoriDifferenceDin99o) metric that can be expressed as a simple Euclidean distance. The latest iteration of the the standard, DIN99o, is available in Cartesian (`dlab`) and plar (`dlch`) form.
@@ -230,6 +261,8 @@ The DIN99o color space in Cartesian form.
 
 Serialized as `color(--din99o-lab l a b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `dlch`
 
 The DIN99o color space in cylindrical form.
@@ -242,6 +275,8 @@ The DIN99o color space in cylindrical form.
 
 Serialized as `color(--din99o-lch l c h)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 ### Oklab, Oklch, Okhsl, Okhsv
 
 The [Oklab color space](https://bottosson.github.io/posts/oklab/), in Cartesian (Lab) and cylindrical (LCh) forms. It uses the D65 standard illuminant. 
@@ -260,6 +295,8 @@ The Oklab color space in Cartesian form.
 
 Serialized as `oklab(l a b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `oklch`
 
 The Oklab color space in cylindrical form.
@@ -272,6 +309,8 @@ The Oklab color space in cylindrical form.
 
 Serialized as `oklch(l c h)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 ### `okhsl`
 
 | Channel | Range      | Description       |
@@ -282,6 +321,8 @@ Serialized as `oklch(l c h)`, with the `none` keyword for any missing color chan
 
 Serialized as `color(--okhsl h s l)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 ### `okhsv`
 
 | Channel | Range      | Description       |
@@ -292,6 +333,8 @@ Serialized as `color(--okhsl h s l)`, with the `none` keyword for any missing co
 
 Serialized as `color(--okhsv h s v)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### Further reading
 
 * [An interactive review of Oklab](https://raphlinus.github.io/color/2021/01/18/oklab-critique.html) by Raph Levien
@@ -316,6 +359,8 @@ The J<sub>z</sub>a<sub>z</sub>b<sub>z</sub> color space in Cartesian form.
 
 Serialized as `color(--jzazbz j a b)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `jch`
 
 The J<sub>z</sub>a<sub>z</sub>b<sub>z</sub> color space in cylindrical form.
@@ -328,6 +373,8 @@ The J<sub>z</sub>a<sub>z</sub>b<sub>z</sub> color space in cylindrical form.
 
 Serialized as `color(--jzczhz j c h)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 ### YIQ (`yiq`)
 
 [YIQ](https://en.wikipedia.org/wiki/YIQ) is the color space used by the NTSC color TV system. It contains the following channels:
@@ -340,6 +387,8 @@ Serialized as `color(--jzczhz j c h)`, with the `none` keyword for any missing c
 
 Serialized as `color(--yiq y i q)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 The conversion matrices between the sRGB and YIQ color spaces are taken from:
 
 > Yuriy Kotsarenko, Fernando Ramos, [_Measuring perceived color difference using YIQ NTSC transmission color space in mobile applications_](http://www.progmat.uaem.mx:8080/artVol2Num2/Articulo3Vol2Num2.pdf), Programación Matemática y Software (2010), Vol. 2, No 2.
@@ -360,6 +409,8 @@ The CIE XYZ color space in respect to the D50 standard illuminant.
 
 Serialized as `color(xyz-d50 x y z)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 #### `xyz65`
 
 The CIE XYZ color space in respect to the D65 standard illuminant.
@@ -372,6 +423,8 @@ The CIE XYZ color space in respect to the D65 standard illuminant.
 
 Serialized as `color(xyz-d65 x y z)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.
+
 ### XYB 
 
 The XYB color model is part of [the JPEG XL Image Coding System](https://ds.jpeg.org/whitepapers/jpeg-xl-whitepaper.pdf), as an <q>LMS-based colour model inspired by the human visual system, facilitating perceptually uniform quantization. It uses a gamma of 3 for computationally efficient decoding</q>. 
@@ -388,6 +441,8 @@ It has the default _Chroma from Luma_ adjustment applied (effectively Y is subtr
 | `y`       | `[0, 0.8453]`≈     | Luma           |
 | `b`       | `[ -0.2778, 0.3880 ]` ≈ | Blue-yellow component           |
 
+Does not have gamut limits.
+
 ### Cubehelix
 
 [The Cubehelix color scheme](https://www.mrao.cam.ac.uk/~dag/CUBEHELIX/) was described by Dave Green in this paper:
@@ -408,3 +463,4 @@ The channels in the `cubehelix` color space maintain the conventions from D3, na
 
 Serialized as `color(--cubehelix h s l)`, with the `none` keyword for any missing color channel. An explicit `alpha < 1` is included as ` / alpha`.
 
+Does not have gamut limits.