[Color 4] Require an explicit gamut mapping method

accepted/color-4-new-spaces-js.d.ts.md

@@ -116,6 +116,8 @@ export type HueInterpolationMethod =
   | 'increasing'
   | 'longer'
   | 'shorter';
+
+export type GamutMapMethod = 'clip' | 'local-minde';
 ```
 
 ### New Color Functions

accepted/color-4-new-spaces.md

@@ -327,11 +327,12 @@ one or more of its channels out of bounds, like `rgb(300 0 0)`).
 
 #### `color.to-gamut()`
 
-This function returns a color that is in the given gamut, using the current CSS
-Color 4's `local-minde` algorithm to 'map' out-of-gamut colors into the desired
-gamut with as little perceptual change as possible. In many cases this can be
-more reliable for generating fallback values, rather than the 'channel clipping'
-approach used by current browsers.
+This function returns a color that is in the given gamut, using the given
+mapping algorithm to convert out-of-gamut colors into the desired gamut with as
+little perceptual change as possible. The current recommended algorithm is
+`local-minde`, which is defined in the current candidate recommendation of CSS
+Color 4, which can in many cases be more reliable for generating fallback values
+than the "channel clipping" approach used by current browsers.
 
 ```scss
 $green: oklch(0.8 2 150);

js-api-doc/index.d.ts

@@ -58,6 +58,7 @@ export {
   ColorSpaceLab,
   ColorSpaceRgb,
   ColorSpaceXyz,
+  GamutMapMethod,
   HueInterpolationMethod,
   KnownColorSpace,
   ListSeparator,

js-api-doc/value/color.d.ts

@@ -79,6 +79,25 @@ export type HueInterpolationMethod =
   | 'longer'
   | 'shorter';
 
+/**
+ * Methods by which colors in bounded spaces can be mapped to within their
+ * gamut.
+ *
+ * * `local-minde`: The algorithm specified in [the original Color Level 4
+ *   candidate recommendation]. This maps in the Oklch color space, using the
+ *   [deltaEOK] color difference formula and the [local-MINDE] improvement.
+ *
+ * * `clip`: Clamp each color channel that's outside the gamut to the minimum or
+ *   maximum value for that channel. This algorithm will produce poor visual
+ *   results, but it may be useful to match the behavior of other situations in
+ *   which a color can be clipped.
+ *
+ * [the original Color Level 4 candidate recommendation]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#css-gamut-mapping
+ * [deltaEok]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#color-difference-OK
+ * [local-MINDE]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#GM-chroma-local-MINDE
+ */
+export type GamutMapMethod = 'clip' | 'local-minde';
+
 /**
  * Sass's [color type](https://sass-lang.com/documentation/values/colors).
  *
@@ -269,25 +288,12 @@ export class SassColor extends Value {
 
   /**
    * Returns a copy of this color, modified so it is in-gamut for the specified
-   * `space`—or the current color space if `space` is not specified—using one of
-   * the following methods to map out-of-gamut colors into the desired gamut:
-   *
-   * * `local-minde`: The algorithm specified in [the original Color Level 4
-   *   candidate recommendation]. This maps in the Oklch color space, using the
-   *   [deltaEOK] color difference formula and the [local-MINDE] improvement.
-   *
-   * * `clip`: Clamp each color channel that's outside the gamut to the minimum
-   *   or maximum value for that channel. This algorithm will produce poor
-   *   visual results, but it may be useful to match the behavior of other
-   *   situations in which a color can be clipped.
-   *
-   * [the original Color Level 4 candidate recommendation]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#css-gamut-mapping
-   * [the original Color Level 4 candidate recommendation]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#color-difference-OK
-   * [local-MINDE]: https://www.w3.org/TR/2024/CRD-css-color-4-20240213/#GM-chroma-local-MINDE
+   * `space`—or the current color space if `space` is not specified—using
+   * `method` to map out-of-gamut colors into the desired gamut.
    */
   toGamut(options: {
     space?: KnownColorSpace;
-    method: 'clip' | 'local-minde';
+    method: GamutMapMethod;
   }): SassColor;
 
   /**

js-api-doc/value/index.d.ts

@@ -34,6 +34,7 @@ export {
   ColorSpaceXyz,
   ChannelNameXyz,
   ChannelName,
+  GamutMapMethod,
   KnownColorSpace,
   PolarColorSpace,
   RectangularColorSpace,

spec/js-api/index.d.ts.md

@@ -95,6 +95,7 @@ export {
   ColorSpaceLab,
   ColorSpaceRgb,
   ColorSpaceXyz,
+  GamutMapMethod,
   HueInterpolationMethod,
   KnownColorSpace,
   ListSeparator,

spec/js-api/value/color.d.ts.md

@@ -26,6 +26,7 @@ import {Value} from './index';
   * [`PolarColorSpace`](#polarcolorspace)
   * [`RectangularColorSpace`](#rectangularcolorspace)
   * [`HueInterpolationMethod`](#hueinterpolationmethod)
+  * [`GamutMapMethod`](#gamutmapmethod)
   * [`SassColor`](#sasscolor)
     * [`internal`](#internal)
     * [Constructor](#constructor)
@@ -224,6 +225,14 @@ export type HueInterpolationMethod =
   | 'shorter';
 ```
 
+### `GamutMapMethod`
+
+Methods by which colors in bounded spaces can be mapped to within their gamut.
+
+```ts
+export type GamutMapMethod = 'clip' | 'local-minde';
+```
+
 ### `SassColor`
 
 The JS API representation of a Sass color.
@@ -557,11 +566,11 @@ Returns the result of [`color.to-gamut(internal, space, method)`].
 ```ts
 toGamut(options: {
   space?: KnownColorSpace;
-  method: 'clip' | 'local-minde';
+  method: GamutMapMethod;
 }): SassColor;
 ```
 
-[`color.to-gamut(internal, space, method)`]: ./color-4-new-spaces.md#colorto-gamut-1
+[`color.to-gamut(internal, space, method)`]: ../../../accepted/color-4-new-spaces.md#colorto-gamut-1
 
 #### `channelsOrNull`
 

spec/js-api/value/index.d.ts.md

@@ -37,6 +37,7 @@ export {
   ColorSpaceXyz,
   ChannelNameXyz,
   ChannelName,
+  GamutMapMethod,
   KnownColorSpace,
   PolarColorSpace,
   RectangularColorSpace,