Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Color 4] Update to support the latest specs #2125

Merged
merged 20 commits into from
Apr 10, 2024
Merged
Show file tree
Hide file tree
Changes from 19 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,12 @@
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**: 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
Expand Down
193 changes: 121 additions & 72 deletions lib/src/functions/color.dart
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@
// https://opensource.org/licenses/MIT.

import 'dart:collection';
import 'dart:math' as math;

import 'package:collection/collection.dart';

Expand Down Expand Up @@ -423,11 +424,21 @@ final module = BuiltInModule("color", functions: <Callable>[
(arguments) => SassString(arguments.first.assertColor("color").space.name,
quotes: false)),

_function(
"to-space",
r"$color, $space",
(arguments) =>
_colorInSpace(arguments[0], arguments[1].assertString("space"))),
_function("to-space", r"$color, $space", (arguments) {
var converted = _colorInSpace(arguments[0], arguments[1]);
// `color.to-space()` never returns missing channels for legacy color
// spaces because they're less compatible and users are probably using a
// legacy space because they want a highly compatible color.
return converted.isLegacy &&
(converted.isChannel0Missing ||
converted.isChannel1Missing ||
converted.isChannel2Missing ||
converted.isAlphaMissing) &&
converted.space != (arguments[0] as SassColor).space
? SassColor.forSpaceInternal(converted.space, converted.channel0,
converted.channel1, converted.channel2, converted.alpha)
: converted;
}),

_function("is-legacy", r"$color",
(arguments) => SassBoolean(arguments[0].assertColor("color").isLegacy)),
Expand Down Expand Up @@ -459,7 +470,7 @@ final module = BuiltInModule("color", functions: <Callable>[
? ColorSpace.srgb
: space)
.toGamut()
.toSpace(space);
.toSpace(color.space);
}),

_function("channel", r"$color, $channel, $space: null", (arguments) {
Expand Down Expand Up @@ -706,7 +717,7 @@ SassColor _updateComponents(List<Value> arguments,
: _colorInSpace(originalColor, spaceKeyword ?? sassNull);

var oldChannels = color.channels;
var channelArgs = List<SassNumber?>.filled(oldChannels.length, null);
var channelArgs = List<Value?>.filled(oldChannels.length, null);
var channelInfo = color.space.channels;
for (var (name, value) in keywords.pairs) {
var channelIndex = channelInfo.indexWhere((info) => name == info.name);
Expand All @@ -716,50 +727,75 @@ SassColor _updateComponents(List<Value> arguments,
name);
}

channelArgs[channelIndex] = value.assertNumber(name);
channelArgs[channelIndex] = value;
}

var result = change
? _changeColor(color, channelArgs, alphaArg)
: scale
? _scaleColor(color, channelArgs, alphaArg)
: _adjustColor(color, channelArgs, alphaArg);
SassColor result;
if (change) {
result = _changeColor(color, channelArgs, alphaArg);
} else {
var channelNumbers = [
for (var i = 0; i < channelInfo.length; i++)
channelArgs[i]?.assertNumber(channelInfo[i].name)
];
result = scale
? _scaleColor(color, channelNumbers, alphaArg)
: _adjustColor(color, channelNumbers, alphaArg);
}

return result.toSpace(originalColor.space);
}

/// Returns a copy of [color] with its channel values replaced by those in
/// [channelArgs] and [alphaArg], if specified.
SassColor _changeColor(
SassColor color, List<SassNumber?> channelArgs, SassNumber? alphaArg) {
var latterUnits =
color.space == ColorSpace.hsl || color.space == ColorSpace.hwb
? '%'
: null;
return _colorFromChannels(
color.space,
channelArgs[0] ?? SassNumber(color.channel0),
channelArgs[1] ?? SassNumber(color.channel1, latterUnits),
channelArgs[2] ?? SassNumber(color.channel2, latterUnits),
alphaArg.andThen((alphaArg) {
if (!alphaArg.hasUnits) {
return alphaArg.value;
} else if (alphaArg.hasUnit('%')) {
return alphaArg.value / 100;
} else {
warnForDeprecation(
"\$alpha: Passing a unit other than % ($alphaArg) is "
"deprecated.\n"
"\n"
"To preserve current behavior: "
"${alphaArg.unitSuggestion('alpha')}\n"
"\n"
"See https://sass-lang.com/d/function-units",
Deprecation.functionUnits);
return alphaArg.value;
}
}) ??
color.alpha);
SassColor color, List<Value?> channelArgs, SassNumber? alphaArg) =>
_colorFromChannels(
color.space,
_channelForChange(channelArgs[0], color, 0),
_channelForChange(channelArgs[1], color, 1),
_channelForChange(channelArgs[2], color, 2),
alphaArg.andThen((alphaArg) {
if (!alphaArg.hasUnits) {
return alphaArg.value;
} else if (alphaArg.hasUnit('%')) {
return alphaArg.value / 100;
} else {
warnForDeprecation(
"\$alpha: Passing a unit other than % ($alphaArg) is "
"deprecated.\n"
"\n"
"To preserve current behavior: "
"${alphaArg.unitSuggestion('alpha')}\n"
"\n"
"See https://sass-lang.com/d/function-units",
Deprecation.functionUnits);
return alphaArg.value;
}
}) ??
color.alpha,
clamp: false);

/// Returns the value for a single channel in `color.change()`.
///
/// The [channelArg] is the argument passed in by the user, if one exists. If no
/// argument is passed, the channel at [index] in [color] is used instead.
SassNumber? _channelForChange(Value? channelArg, SassColor color, int channel) {
if (channelArg == null) {
return switch (color.channelsOrNull[channel]) {
var value? => SassNumber(
value,
(color.space == ColorSpace.hsl || color.space == ColorSpace.hwb) &&
channel > 0
? '%'
: null),
_ => null
};
}
if (_isNone(channelArg)) return null;
if (channelArg is SassNumber) return channelArg;
throw SassScriptException('$channelArg is not a number or unquoted "none".',
color.space.channels[channel].name);
}

/// Returns a copy of [color] with its channel values scaled by the values in
Expand Down Expand Up @@ -852,10 +888,15 @@ double _adjustChannel(ColorSpace space, ColorChannel channel, double oldValue,
adjustmentArg = SassNumber(adjustmentArg.value);
}

var result = oldValue + _channelFromValue(channel, adjustmentArg)!;
return space.isStrictlyBounded && channel is LinearChannel
? fuzzyClamp(result, channel.min, channel.max)
: result;
var result =
oldValue + _channelFromValue(channel, adjustmentArg, clamp: false)!;
return switch (channel) {
LinearChannel(lowerClamped: true, :var min) when result < min =>
oldValue < min ? math.max(oldValue, result) : min,
LinearChannel(upperClamped: true, :var max) when result > max =>
oldValue > max ? math.min(oldValue, result) : max,
_ => result
};
}

/// Given a map of arguments passed to [_updateComponents] for a legacy color,
Expand Down Expand Up @@ -1311,24 +1352,28 @@ Value? _parseNumberOrNone(String text) {

/// Creates a [SassColor] for the given [space] from the given channel values,
/// or throws a [SassScriptException] if the channel values are invalid.
///
/// If [clamp] is true, this will clamp any clamped channels.
SassColor _colorFromChannels(ColorSpace space, SassNumber? channel0,
SassNumber? channel1, SassNumber? channel2, double? alpha,
{bool fromRgbFunction = false}) {
{bool clamp = true, bool fromRgbFunction = false}) {
switch (space) {
case ColorSpace.hsl:
if (channel1 != null) _checkPercent(channel1, 'saturation');
if (channel2 != null) _checkPercent(channel2, 'lightness');
return SassColor.hsl(
channel0.andThen((channel0) => _angleValue(channel0, 'hue')),
channel1?.value.clamp(0, 100).toDouble(),
channel2?.value.clamp(0, 100).toDouble(),
_channelFromValue(space.channels[1], _forcePercent(channel1),
clamp: clamp),
_channelFromValue(space.channels[2], _forcePercent(channel2),
clamp: clamp),
alpha);

case ColorSpace.hwb:
channel1?.assertUnit('%', 'whiteness');
channel2?.assertUnit('%', 'blackness');
var whiteness = channel1?.value.clamp(0, 100).toDouble();
var blackness = channel2?.value.clamp(0, 100).toDouble();
var whiteness = channel1?.value.toDouble();
var blackness = channel2?.value.toDouble();

if (whiteness != null &&
blackness != null &&
Expand All @@ -1346,44 +1391,48 @@ SassColor _colorFromChannels(ColorSpace space, SassNumber? channel0,

case ColorSpace.rgb:
return SassColor.rgbInternal(
_channelFromValue(space.channels[0], channel0),
_channelFromValue(space.channels[1], channel1),
_channelFromValue(space.channels[2], channel2),
_channelFromValue(space.channels[0], channel0, clamp: clamp),
_channelFromValue(space.channels[1], channel1, clamp: clamp),
_channelFromValue(space.channels[2], channel2, clamp: clamp),
alpha,
fromRgbFunction ? ColorFormat.rgbFunction : null);

case ColorSpace.lab ||
ColorSpace.lch ||
ColorSpace.oklab ||
ColorSpace.oklch:
return SassColor.forSpaceInternal(
space,
_channelFromValue(space.channels[0], channel0).andThen((lightness) =>
fuzzyClamp(
lightness, 0, (space.channels[0] as LinearChannel).max)),
_channelFromValue(space.channels[1], channel1),
_channelFromValue(space.channels[2], channel2),
alpha);

default:
return SassColor.forSpaceInternal(
space,
_channelFromValue(space.channels[0], channel0),
_channelFromValue(space.channels[1], channel1),
_channelFromValue(space.channels[2], channel2),
_channelFromValue(space.channels[0], channel0, clamp: clamp),
_channelFromValue(space.channels[1], channel1, clamp: clamp),
_channelFromValue(space.channels[2], channel2, clamp: clamp),
alpha);
}
}

/// Returns [number] with unit `'%'` regardless of its original unit.
SassNumber? _forcePercent(SassNumber? number) => switch (number) {
null => null,
SassNumber(numeratorUnits: ['%'], denominatorUnits: []) => number,
_ => SassNumber(number.value, '%')
};

/// Converts a channel value from a [SassNumber] into a [double] according to
/// [channel].
double? _channelFromValue(ColorChannel channel, SassNumber? value) =>
///
/// If [clamp] is true, this clamps [value] according to [channel]'s clamping
/// rules.
double? _channelFromValue(ColorChannel channel, SassNumber? value,
{bool clamp = true}) =>
value.andThen((value) => switch (channel) {
LinearChannel(requiresPercent: true) when !value.hasUnit('%') =>
throw SassScriptException(
'Expected $value to have unit "%".', channel.name),
LinearChannel() =>
LinearChannel(lowerClamped: false, upperClamped: false) =>
_percentageOrUnitless(value, channel.max, channel.name),
LinearChannel() when !clamp =>
_percentageOrUnitless(value, channel.max, channel.name),
LinearChannel(:var lowerClamped, :var upperClamped) =>
_percentageOrUnitless(value, channel.max, channel.name).clamp(
lowerClamped ? channel.min : double.negativeInfinity,
upperClamped ? channel.max : double.infinity),
_ => value.coerceValueToUnit('deg', channel.name) % 360
});

Expand Down
5 changes: 5 additions & 0 deletions lib/src/util/number.dart
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,11 @@ double fuzzyClamp(double number, double min, double max) {
return number;
}

/// Returns whether [number] is within [min] and [max] inclusive, using fuzzy
/// equality.
bool fuzzyInRange(double number, num min, num max) =>
fuzzyGreaterThanOrEquals(number, min) && fuzzyLessThanOrEquals(number, max);

/// Returns [number] if it's within [min] and [max], or `null` if it's not.
///
/// If [number] is [fuzzyEquals] to [min] or [max], it's clamped to the
Expand Down