Merge pull request #2341 from sass/feature.color-4

Merge feature.color-4 into main

CHANGELOG.md

@@ -1,11 +1,199 @@
 ## 1.79.0
 
+* **Breaking change**: Passing a number with unit `%` to the `$alpha` parameter
+  of `color.change()`, `color.adjust()`, `change-color()`, and `adjust-color()`
+  is now interpreted as a percentage, instead of ignoring the unit. For example,
+  `color.change(red, $alpha: 50%)` now returns `rgb(255 0 0 / 0.5)`.
+
+* **Potentially breaking compatibility fix**: Sass no longer rounds RGB channels
+  to the nearest integer. This means that, for example, `rgb(0 0 1) != rgb(0 0
+  0.6)`. This matches the latest version of the CSS spec and browser behavior.
+
+* **Potentially breaking compatibility fix**: Passing large positive or negative
+  values to `color.adjust()` can now cause a color's channels to go outside that
+  color's gamut. In most cases this will currently be clipped by the browser and
+  end up showing the same color as before, but once browsers implement gamut
+  mapping it may produce a different result.
+
+* Add support for CSS Color Level 4 [color spaces]. Each color value now tracks
+  its color space along with the values of each channel in that color space.
+  There are two general principles to keep in mind when dealing with new color
+  spaces:
+
+  1. With the exception of legacy color spaces (`rgb`, `hsl`, and `hwb`), colors
+     will always be emitted in the color space they were defined in unless
+     they're explicitly converted.
+
+  2. The `color.to-space()` function is the only way to convert a color to
+     another color space. Some built-in functions may do operations in a
+     different color space, but they'll always convert back to the original space
+     afterwards.
+
+* `rgb` colors can now have non-integer channels and channels outside the normal
+  gamut of 0-255. These colors are always emitted using the `rgb()` syntax so
+  that modern browsers that are being displayed on wide-gamut devices can
+  display the most accurate color possible.
+
+* Add support for all the new color syntax defined in Color Level 4, including:
+
+  * `oklab()`, `oklch()`, `lab()`, and `lch()` functions;
+  * a top-level `hwb()` function that matches the space-separated CSS syntax;
+  * and a `color()` function that supports the `srgb`, `srgb-linear`,
+    `display-p3`, `a98-rgb`, `prophoto-rgb`, `rec2020`, `xyz`, `xyz-d50`, and
+    `xyz-d65` color spaces.
+
+* Add new functions for working with color spaces:
+
+  * `color.to-space($color, $space)` converts `$color` to the given `$space`. In
+    most cases this conversion is lossless—the color may end up out-of-gamut for
+    the destination color space, but browsers will generally display it as best
+    they can regardless. However, the `hsl` and `hwb` spaces can't represent
+    out-of-gamut colors and so will be clamped.
+
+  * `color.channel($color, $channel, $space: null)` returns the value of the
+    given `$channel` in `$color`, after converting it to `$space` if necessary.
+    It should be used instead of the old channel-specific functions such as
+    `color.red()` and `color.hue()`.
+
+  * `color.same($color1, $color2)` returns whether two colors represent the same
+    color even across color spaces. It differs from `$color1 == $color2` because
+    `==` never consider colors in different (non-legacy) spaces as equal.
+
+  * `color.is-in-gamut($color, $space: null)` returns whether `$color` is
+    in-gamut for its color space (or `$space` if it's passed).
+
+  * `color.to-gamut($color, $space: null)` returns `$color` constrained to its
+    space's gamut (or to `$space`'s gamut, if passed). This is generally not
+    recommended since even older browsers will display out-of-gamut colors as
+    best they can, but it may be necessary in some cases.
+
+  * `color.space($color)`: Returns the name of `$color`'s color space.
+
+  * `color.is-legacy($color)`: Returns whether `$color` is in a legacy color
+    space (`rgb`, `hsl`, or `hwb`).
+
+  * `color.is-powerless($color, $channel, $space: null)`: Returns whether the
+    given `$channel` of `$color` is powerless in `$space` (or its own color
+    space). A channel is "powerless" if its value doesn't affect the way the
+    color is displayed, such as hue for a color with 0 chroma.
+
+  * `color.is-missing($color, $channel)`: Returns whether `$channel`'s value is
+    missing in `$color`. Missing channels can be explicitly specified using the
+    special value `none` and can appear automatically when `color.to-space()`
+    returns a color with a powerless channel. Missing channels are usually
+    treated as 0, except when interpolating between two colors and in
+    `color.mix()` where they're treated as the same value as the other color.
+
+* Update existing functions to support color spaces:
+
+  * `hsl()` and `color.hwb()` no longer forbid out-of-bounds values. Instead,
+    they follow the CSS spec by clamping them to within the allowed range.
+
+  * `color.change()`, `color.adjust()`, and `color.scale()` now support all
+    channels of all color spaces. However, if you want to modify a channel
+    that's not in `$color`'s own color space, you have to explicitly specify the
+    space with the `$space` parameter. (For backwards-compatibility, this
+    doesn't apply to legacy channels of legacy colors—for example, you can still
+    adjust an `rgb` color's saturation without passing `$space: hsl`).
+
+  * `color.mix()` and `color.invert()` now support the standard CSS algorithm
+    for interpolating between two colors (the same one that's used for gradients
+    and animations). To use this, pass the color space to use for interpolation
+    to the `$method` parameter. For polar color spaces like `hsl` and `oklch`,
+    this parameter also allows you to specify how hue interpolation is handled.
+
+  * `color.complement()` now supports a `$space` parameter that indicates which
+    color space should be used to take the complement.
+
+  * `color.grayscale()` now operates in the `oklch` space for non-legacy colors.
+
+  * `color.ie-hex-str()` now automatically converts its color to the `rgb` space
+    and gamut-maps it so that it can continue to take colors from any color
+    space.
+
+[color spaces]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value
+
+* The following functions are now deprecated, and uses should be replaced with
+  the new color-space-aware functions defined above:
+
+  * The `color.red()`, `color.green()`, `color.blue()`, `color.hue()`,
+    `color.saturation()`, `color.lightness()`, `color.whiteness()`, and
+    `color.blackness()` functions, as well as their global counterparts, should
+    be replaced with calls to `color.channel()`.
+
+  * The global `adjust-hue()`, `saturate()`, `desaturate()`, `lighten()`,
+    `darken()`, `transaprentize()`, `fade-out()`, `opacify()`, and `fade-in()`
+    functions should be replaced by `color.adjust()` or `color.scale()`.
+
 * Add a `global-builtin` future deprecation, which can be opted-into with the
   `--future-deprecation` flag or the `futureDeprecations` option in the JS or
   Dart API. This emits warnings when any global built-in functions that are
   now available in `sass:` modules are called. It will become active by default
   in an upcoming release alongside the `@import` deprecation.
 
+### Dart API
+
+* Added a `ColorSpace` class which represents the various color spaces defined
+  in the CSS spec.
+
+* Added `SassColor.space` which returns a color's color space.
+
+* Added `SassColor.channels` and `.channelsOrNull` which returns a list
+  of channel values, with missing channels converted to 0 or exposed as null,
+  respectively.
+
+* Added `SassColor.isLegacy`, `.isInGamut`, `.channel()`, `.isChannelMissing()`,
+  `.isChannelPowerless()`, `.toSpace()`, `.toGamut()`, `.changeChannels()`, and
+  `.interpolate()` which do the same thing as the Sass functions of the
+  corresponding names.
+
+* `SassColor.rgb()` now allows out-of-bounds and non-integer arguments.
+
+* `SassColor.hsl()` and `.hwb()` now allow out-of-bounds arguments.
+
+* Added `SassColor.hwb()`, `.srgb()`, `.srgbLinear()`, `.displayP3()`,
+  `.a98Rgb()`, `.prophotoRgb()`, `.rec2020()`, `.xyzD50()`, `.xyzD65()`,
+  `.lab()`, `.lch()`, `.oklab()`, `.oklch()`, and `.forSpace()` constructors.
+
+* Deprecated `SassColor.red`, `.green`, `.blue`, `.hue`, `.saturation`,
+  `.lightness`, `.whiteness`, and `.blackness` in favor of
+  `SassColor.channel()`.
+
+* Deprecated `SassColor.changeRgb()`, `.changeHsl()`, and `.changeHwb()` in
+  favor of `SassColor.changeChannels()`.
+
+* Added `SassNumber.convertValueToUnit()` as a shorthand for
+  `SassNumber.convertValue()` with a single numerator.
+
+* Added `InterpolationMethod` and `HueInterpolationMethod` which collectively
+  represent the method to use to interpolate two colors.
+
+### JS API
+
+* Modify `SassColor` to accept a new `space` option, with support for all the
+  new color spaces defined in Color Level 4.
+
+* Add `SassColor.space` which returns a color's color space.
+
+* Add `SassColor.channels` and `.channelsOrNull` which returns a list of channel
+  values, with missing channels converted to 0 or exposed as null, respectively.
+
+* Add `SassColor.isLegacy`, `.isInGamut()`, `.channel()`, `.isChannelMissing()`,
+  `.isChannelPowerless()`, `.toSpace()`, `.toGamut()`, `.change()`, and
+  `.interpolate()` which do the same thing as the Sass functions of the
+  corresponding names.
+
+* Deprecate `SassColor.red`, `.green`, `.blue`, `.hue`, `.saturation`,
+  `.lightness`, `.whiteness`, and `.blackness` in favor of
+  `SassColor.channel()`.
+
+### Embedded Sass
+
+* Add `Color` SassScript value, with support for all the new color spaces
+  defined in Color Level 4.
+
+* Remove `RgbColor`, `HslColor` and `HwbColor` SassScript values.
+
 ## 1.78.0
 
 * The `meta.feature-exists` function is now deprecated. This deprecation is

lib/sass.dart

@@ -31,7 +31,12 @@ export 'src/importer.dart';
 export 'src/logger.dart' show Logger;
 export 'src/syntax.dart';
 export 'src/value.dart'
-    hide ColorFormat, SassApiColor, SassApiValue, SpanColorFormat;
+    hide
+        ColorChannel,
+        ColorFormat,
+        LinearChannel,
+        SassApiColorSpace,
+        SpanColorFormat;
 export 'src/visitor/serialize.dart' show OutputStyle;
 export 'src/evaluation_context.dart' show warn;
 

lib/src/deprecation.dart

@@ -15,7 +15,7 @@ enum Deprecation {
   // DO NOT EDIT. This section was generated from the language repo.
   // See tool/grind/generate_deprecations.dart for details.
   //
-  // Checksum: bf841a728263bf7efc2a85a091330a1f8074e067
+  // Checksum: 5470e7252641d3eaa7093b072b52e423c3b77375
 
   /// Deprecation for passing a string directly to meta.call().
   callString('call-string',
@@ -99,6 +99,16 @@ enum Deprecation {
   featureExists('feature-exists',
       deprecatedIn: '1.78.0', description: 'meta.feature-exists'),
 
+  /// Deprecation for certain uses of built-in sass:color functions.
+  color4Api('color-4-api',
+      deprecatedIn: '1.79.0',
+      description: 'Certain uses of built-in sass:color functions.'),
+
+  /// Deprecation for using global color functions instead of sass:color.
+  colorFunctions('color-functions',
+      deprecatedIn: '1.79.0',
+      description: 'Using global color functions instead of sass:color.'),
+
   /// Deprecation for @import rules.
   import.future('import', description: '@import rules.'),
 

lib/src/embedded/protofier.dart

@@ -53,17 +53,12 @@ final class Protofier {
           ..quoted = value.hasQuotes;
       case SassNumber():
         result.number = _protofyNumber(value);
-      case SassColor(hasCalculatedHsl: true):
-        result.hslColor = Value_HslColor()
-          ..hue = value.hue * 1.0
-          ..saturation = value.saturation * 1.0
-          ..lightness = value.lightness * 1.0
-          ..alpha = value.alpha * 1.0;
       case SassColor():
-        result.rgbColor = Value_RgbColor()
-          ..red = value.red
-          ..green = value.green
-          ..blue = value.blue
+        result.color = Value_Color()
+          ..space = value.space.name
+          ..channel1 = value.channel0
+          ..channel2 = value.channel1
+          ..channel3 = value.channel2
           ..alpha = value.alpha * 1.0;
       case SassArgumentList():
         _argumentLists.add(value);
@@ -181,17 +176,85 @@ final class Protofier {
         case Value_Value.number:
           return _deprotofyNumber(value.number);
 
-        case Value_Value.rgbColor:
-          return SassColor.rgb(value.rgbColor.red, value.rgbColor.green,
-              value.rgbColor.blue, value.rgbColor.alpha);
-
-        case Value_Value.hslColor:
-          return SassColor.hsl(value.hslColor.hue, value.hslColor.saturation,
-              value.hslColor.lightness, value.hslColor.alpha);
-
-        case Value_Value.hwbColor:
-          return SassColor.hwb(value.hwbColor.hue, value.hwbColor.whiteness,
-              value.hwbColor.blackness, value.hwbColor.alpha);
+        case Value_Value.color:
+          var space = ColorSpace.fromName(value.color.space);
+          switch (space) {
+            case ColorSpace.rgb:
+              return SassColor.rgb(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+
+            case ColorSpace.hsl:
+              return SassColor.hsl(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+
+            case ColorSpace.hwb:
+              return SassColor.hwb(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+
+            case ColorSpace.lab:
+              return SassColor.lab(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+            case ColorSpace.oklab:
+              return SassColor.oklab(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+
+            case ColorSpace.lch:
+              return SassColor.lch(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+            case ColorSpace.oklch:
+              return SassColor.oklch(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+
+            case ColorSpace.srgb:
+              return SassColor.srgb(value.color.channel1, value.color.channel2,
+                  value.color.channel3, value.color.alpha);
+            case ColorSpace.srgbLinear:
+              return SassColor.srgbLinear(
+                  value.color.channel1,
+                  value.color.channel2,
+                  value.color.channel3,
+                  value.color.alpha);
+            case ColorSpace.displayP3:
+              return SassColor.displayP3(
+                  value.color.channel1,
+                  value.color.channel2,
+                  value.color.channel3,
+                  value.color.alpha);
+            case ColorSpace.a98Rgb:
+              return SassColor.a98Rgb(
+                  value.color.channel1,
+                  value.color.channel2,
+                  value.color.channel3,
+                  value.color.alpha);
+            case ColorSpace.prophotoRgb:
+              return SassColor.prophotoRgb(
+                  value.color.channel1,
+                  value.color.channel2,
+                  value.color.channel3,
+                  value.color.alpha);
+            case ColorSpace.rec2020:
+              return SassColor.rec2020(
+                  value.color.channel1,
+                  value.color.channel2,
+                  value.color.channel3,
+                  value.color.alpha);
+
+            case ColorSpace.xyzD50:
+              return SassColor.xyzD50(
+                  value.color.channel1,
+                  value.color.channel2,
+                  value.color.channel3,
+                  value.color.alpha);
+            case ColorSpace.xyzD65:
+              return SassColor.xyzD65(
+                  value.color.channel1,
+                  value.color.channel2,
+                  value.color.channel3,
+                  value.color.alpha);
+
+            default:
+              throw "Unreachable";
+          }
 
         case Value_Value.argumentList:
           if (value.argumentList.id != 0) {
@@ -276,10 +339,8 @@ final class Protofier {
         throw paramsError(error.toString());
       }
 
-      if (value.whichValue() == Value_Value.rgbColor) {
-        name = 'RgbColor.$name';
-      } else if (value.whichValue() == Value_Value.hslColor) {
-        name = 'HslColor.$name';
+      if (value.whichValue() == Value_Value.color) {
+        name = 'Color.$name';
       }
 
       throw paramsError(