Skip to content

Commit

Permalink
Merge pull request #2341 from sass/feature.color-4
Browse files Browse the repository at this point in the history
Merge feature.color-4 into main
  • Loading branch information
nex3 authored Sep 13, 2024
2 parents 4fa5a02 + de181d9 commit 2f0d0da
Show file tree
Hide file tree
Showing 54 changed files with 6,069 additions and 1,122 deletions.
188 changes: 188 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down
7 changes: 6 additions & 1 deletion lib/sass.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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;

Expand Down
12 changes: 11 additions & 1 deletion lib/src/deprecation.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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',
Expand Down Expand Up @@ -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.'),

Expand Down
111 changes: 86 additions & 25 deletions lib/src/embedded/protofier.dart
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down Expand Up @@ -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) {
Expand Down Expand Up @@ -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(
Expand Down
Loading

0 comments on commit 2f0d0da

Please sign in to comment.